diff --git a/source/_static/default.css b/source/_static/default.css index 2524443..d78f833 100644 --- a/source/_static/default.css +++ b/source/_static/default.css @@ -51,7 +51,7 @@ h1, h2 { } -.admonition.warning .admonition-title, .admonition.note .admonition-title { +.admonition.warning .admonition-title, .admonition.note .admonition-title, .admonition.important .admonition-title { background-color: #666; } diff --git a/source/_static/images/service/bitcoin_config.png b/source/_static/images/service/bitcoin_config.png new file mode 100644 index 0000000..8e9af32 Binary files /dev/null and b/source/_static/images/service/bitcoin_config.png differ diff --git a/source/_static/images/service/bitcoin_instructions.png b/source/_static/images/service/bitcoin_instructions.png new file mode 100644 index 0000000..4529e7a Binary files /dev/null and b/source/_static/images/service/bitcoin_instructions.png differ diff --git a/source/_static/images/service/bitcoin_rpc.png b/source/_static/images/service/bitcoin_rpc.png new file mode 100644 index 0000000..9e6e145 Binary files /dev/null and b/source/_static/images/service/bitcoin_rpc.png differ diff --git a/source/_static/images/service/boolean_toggle.png b/source/_static/images/service/boolean_toggle.png new file mode 100644 index 0000000..df07547 Binary files /dev/null and b/source/_static/images/service/boolean_toggle.png differ diff --git a/source/_static/images/service/btcproxy_config.png b/source/_static/images/service/btcproxy_config.png new file mode 100644 index 0000000..cede6fc Binary files /dev/null and b/source/_static/images/service/btcproxy_config.png differ diff --git a/source/_static/images/service/btcproxy_rpc.png b/source/_static/images/service/btcproxy_rpc.png new file mode 100644 index 0000000..9da9efa Binary files /dev/null and b/source/_static/images/service/btcproxy_rpc.png differ diff --git a/source/_static/images/service/service_properties.png b/source/_static/images/service/service_properties.png new file mode 100644 index 0000000..4a8bee2 Binary files /dev/null and b/source/_static/images/service/service_properties.png differ diff --git a/source/contributing/services/config.rst b/source/contributing/services/config.rst index 933ec5b..6db491e 100644 --- a/source/contributing/services/config.rst +++ b/source/contributing/services/config.rst @@ -16,7 +16,6 @@ These files contain a detailed mapping of configuration options with acceptable For example, if the user chooses config option A, then config option B must be between 5 and 10. This enables a simple GUI configuration experience, complete with validations and protections, for users. They do not have to worry about the consequences of a wrong value in a ``.conf`` file. - .. _config_spec: Config Spec =========== @@ -24,15 +23,23 @@ Config Spec Overview -------- +.. figure:: /_static/images/service/bitcoin_config.png + :width: 80% + :alt: Bitcoin Config + This file defines the structure of configuration options your service depends on to run. It additionally can include configuration options that users might want to enable for more advanced or customized usage. Ultimately, these values influence the UI elements for a user to interact with. Specifically, they evaluate to the options available when managing a service, such as: - Prior to service installation when the user needs to be made aware of any necessary dependency configurations - When the user installs a service and the service is in the "Needs Config" state - Whenever a user edits a service config -- When config pointers get updated * (TODO define) +- When config pointers get updated The neat part about this file is that each ValueSpec type gets translated into a specific front end component. For instance, boolean values display as a toggle button. +.. figure:: /_static/images/service/boolean_toggle.png + :width: 80% + :alt: Example boolean toggle + Another advantage is the ability to define default values. These values automatically get populated if the user selects the ``Default`` option when setting up a service in ``Needs Config`` state. This is super convenient for users who want to get up and running quickly. Types @@ -44,24 +51,32 @@ ConfigSpec Type: key: ValueSpec -ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details) + ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details) Implementation Guide -------------------- The following section contains implementation specifications for the ``config_spec.yaml`` file. -- All keys are ``kebab-case`` strings - - keys correspond to the -- All values are one the following specs (ie. ValueSpec type): - - :ref:`boolean ` - - :ref:`enum ` - - :ref:`list ` - - :ref:`number ` - - :ref:`object ` - - :ref:`string ` - - :ref:`union ` - - :ref:`pointer ` +- All keys are ``kebab-case`` strings, which correspond to the service (app) id +- All values are one the following specs (ie. ``ValueSpec`` type): + + :ref:`boolean ` + + :ref:`enum ` + + :ref:`list ` + + :ref:`number ` + + :ref:`object ` + + :ref:`string ` + + :ref:`union ` + + :ref:`pointer ` + - In the examples for each value spec type below, ``Option`` means the key is optional. Otherwise, the key is required. - Descriptions are optional but recommended - Name corresponds to the name of the config field @@ -74,7 +89,7 @@ Boolean Config value specification denoted as a boolean value. A default value is required. -ValueSpec Type: +``ValueSpec`` Type: .. code:: @@ -178,7 +193,7 @@ Example: Number ^^^^^^ -A number value within an optionally defined range. Nullable field is required. If ``nullable: true``, the default is assumed to be ``null`` if it is not provided. +A number value within an optionally defined range. Nullable field is required. If ``nullable`` is true, the default is assumed to be ``null`` if it is not provided. ValueSpec Type: @@ -215,6 +230,8 @@ A nested representation of a ConfigSpec. The object type takes the same structur There is no default option for the object type. Rather, the option ``null-by-default`` should be used to indicate the default as ``null``. If null by default is true, nullable must be true. If null by default is false, nullable could be either. +``unique-by`` indicates whether duplicates can be permitted in the list. + ValueSpec Type: .. code:: @@ -226,9 +243,11 @@ ValueSpec Type: nullable: Boolean null-by-default: Boolean display-as: Option - unique-by: any | all | exactly | not unique + unique-by: UniqueBy spec: ConfigSpec + type UniqueBy = null | string | { any: UniqueBy[] } | { all: UniqueBy[] } + Example: .. code:: yaml @@ -296,6 +315,7 @@ ValueSpec Type: Entropy Type: .. code:: + charset: Option len: integer @@ -336,6 +356,7 @@ The pointer type *points* to a config value on another service installed on Emba ValueSpec Type: .. code:: + type: pointer name: String description: Option @@ -383,8 +404,8 @@ ValueSpec Type; default: Boolean tag: Tag variants: Map - display-as: Option TODO ask aiden if this should be exposed - unique-by: any | all | exactly | notUnique TODO ask aiden + display-as: Option + unique-by: any | all | exactly | notUnique Tag Type: @@ -473,9 +494,9 @@ Config Rules This file defines the configuration rules, or the rule-set that defines dependencies between config variables. -A rule is a boolean expression that we demand to be true. If it is failing, it is not true. +A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser. -They follow the `Backus–Naur `_ metasyntax for writing rules. +They follow the `Backus–Naur `_ meta-syntax for writing rules. Rules are composed of two main concepts: @@ -491,11 +512,11 @@ Variables can be booleans, numbers, or strings, and have a different syntax depe If application does not satisfy a rule, a set of suggestions should be provided. These suggestions are in the form of the operation to preform: - - Set - set the value + - ``Set`` - set the value - - Push - add to the value (such as with a list) + - ``Push`` - add to the value (such as to a list) - - Delete - delete the value + - ``Delete`` - delete the value .. code:: typescript @@ -538,6 +559,4 @@ SetVariant Examples: .. code:: yaml - rule: 'rpc.enable? OR !(''advanced.pruning.mode = "manual")' - description: "RPC must be enabled for manual pruning." - - + description: "RPC must be enabled for manual pruning." \ No newline at end of file diff --git a/source/contributing/services/dependencies.rst b/source/contributing/services/dependencies.rst deleted file mode 100644 index edf9c37..0000000 --- a/source/contributing/services/dependencies.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. _service_dependencies: - -******************** -Service Dependencies -******************** \ No newline at end of file diff --git a/source/contributing/services/docker.rst b/source/contributing/services/docker.rst index c8920d6..9f3ad13 100644 --- a/source/contributing/services/docker.rst +++ b/source/contributing/services/docker.rst @@ -7,7 +7,7 @@ Service Dockerfile Dockerfile ========== -This file defines how to build the image for the service. It declares the environment and building stages for the service. +This file defines how to build the image for the service. It declares the environment and building stages. The Dockerfile is responsible for mounting the service application to whatever volume the manifest specifies, typically ``/root``. Since the build requires specific arm runtime environments, these base images can be imported into the Dockerfile as a starting point so the base system does not need to be completely redefined. This enables importing a specific build environment version that encapsulates any necessary libraries for running the service build, eg. golang, rust. diff --git a/source/contributing/services/docs.rst b/source/contributing/services/docs.rst new file mode 100644 index 0000000..251a0c2 --- /dev/null +++ b/source/contributing/services/docs.rst @@ -0,0 +1,13 @@ +.. _service_docs: + +********************* +Service Documentation +********************* + +Within each wrapper repository should exist a ``docs`` directory. This folder should include any pertinent documentation, instructions, external integrations, or other details about the service that users or developers might find relevant. + +If an ``instructions.md`` file is included, this markdown formatted file will be rendered in the "Instructions" tab within the service detail menu on EmbassyOS: + +.. figure:: /_static/images/service/bitcoin_instructions.png + :width: 80% + :alt: Bitcoin Instructions \ No newline at end of file diff --git a/source/contributing/services/index.rst b/source/contributing/services/index.rst index b3a1e27..9521d92 100644 --- a/source/contributing/services/index.rst +++ b/source/contributing/services/index.rst @@ -8,19 +8,20 @@ This technical guide covers the necessary steps to package up a service for depl While you are waiting to assemble a device, you can begin the process of building your project in the format necessary to run on the Embassy. The sections below outline these steps in detail. -For reference, the `Hello world repository `_ should be used as an example. A project template can be cloned using the ``Use this template`` button in GitHub. +For reference, the `Hello world `_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub. .. toctree:: :maxdepth: 2 - overview - wrapper - docker - manifest - config - dependencies + Overview + Wrapper + Docker + Manifest + Config + Properties + Docs Submission process ------------------ -When you have built and tested your project for EmbassyOS, please send us a submission with the project repository to `dev@start9labs.com`. \ No newline at end of file +When you have built and tested your project for EmbassyOS, please send us a submission with the project repository to ``dev@start9labs.com``. Reach out with questions in the Matrix community `dev channel `_. \ No newline at end of file diff --git a/source/contributing/services/makefile.rst b/source/contributing/services/makefile.rst index 1e89171..0c5ed6e 100644 --- a/source/contributing/services/makefile.rst +++ b/source/contributing/services/makefile.rst @@ -5,8 +5,14 @@ Service Makefile **************** *This file is optional* -It is a convenience if anyone else wants to contribute to project. An alternative is using the nix specification. + +A Makefile serves as a convenience for building and for additional developer contributions to your project. Please reference the GNU `documentation `_ for implementation details. + +An alternative to using ``make`` is to use the `nix `_ specification. This purpose of this file is to: - - read the docker container and build the project - - build all prerequisite for running the docker file, build all dependencies of application, and package into .s9pk (ie. invoke ``appmgr``) \ No newline at end of file + +- Read the docker container and build the project +- Build all prerequisite for running the docker file +- Build all dependencies +- Package ``config.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoke ``appmgr``. \ No newline at end of file diff --git a/source/contributing/services/manifest.rst b/source/contributing/services/manifest.rst index 16ab40d..66d980b 100644 --- a/source/contributing/services/manifest.rst +++ b/source/contributing/services/manifest.rst @@ -4,17 +4,25 @@ Service Manifest **************** +Overview +======== + This file describes the service and it's requirements. It is used by the marketplace to create a service listing. -Important to note is the dependencies key, which contains rules for optional or required other services that are depended on for the developed service to successfully run. +Important of note is the :ref:`dependencies ` key, which contains rules for optional or required other services that are depended on for the service to successfully run. -Formatting: - - Serialization language:``.yaml`` - - Case style: ``kebab-case`` +Formatting +========== -Below are the types and sub-type definitions, with necessary elaborations: +- Serialization language:``.yaml`` +- Case style: ``kebab-case`` -Example ``manifest.yaml`` with field notes: +Type definitions +================ +Below are the types and sub-type definitions, with necessary elaborations. Any item that contains ``Option<>`` is an optional field. + +Example +======= .. code:: yaml @@ -32,6 +40,12 @@ Example ``manifest.yaml`` with field notes: long: String # a link to the release tag notes in GitHub, or a short description TODO character length release_notes: String + # a notification message that should caution the user with any service particularities, eg. beta tech + install_alert: Option + # a notification message warning users of potential problems with uninstalling, such as dependency failures or data loss + uninstall_alert: Option + # a notification message containing warning or details about backup restoration + restore_alert: Option # denoting the existence of instructions.md has_instructions: Boolean # required semver version range of EmbassyOS to run service eg. ">=1.0.0" @@ -44,9 +58,15 @@ Example ``manifest.yaml`` with field notes: tor: String # currently only tar is supported image: - type: String + type: String + # shared memory container size + shm_size_mb: Option # path to mount the image on the volume, ie: /root/bitcoind mount: String + # public directory path + public: Option + # shared directory path + shared: Option # a list of objecting containing the source and destination directories of persistent assets, either that should be copied over during build, or to persist when service started, and if the volume directory should be overwritten when the release is copied over # src: path to file within the assets directory that is in the build directory # dst: path within volume to place it @@ -59,6 +79,7 @@ Example ``manifest.yaml`` with field notes: # A map of dependent services, see below for more details dependencies: Dependencies +.. _dependencies: Dependencies ------------ @@ -99,21 +120,19 @@ Types for ``manifest.yaml`` fields: }] interface DepInfo { - version: String -- TODO correct for VersionReq?, + version: String // ie. 0.11.1.1 optional?: String, description?: String, - config: [ - entry: { - rule: ConfigRule, - description: String, - }, - suggestions: [{ - condition?: ConfigRule, - variant: SuggestionVariant, - }], + config: [ConfigRule], ], } + interface ConfigRule { + rule: String, // ie. '''users.*.name = "lnd"' + description: String, + suggestions: [SuggestionVariant] + } + interface SuggestionVariant { SET: { var: String, @@ -124,71 +143,165 @@ Types for ``manifest.yaml`` fields: }, PUSH: { to: String, - value: Value, @aiden define Value + value: Value, }, } interface SetVariant { - to: string, - to-value: Value, - to-entropy: { - charset: String // 'a-z,A-Z,0-9' + to: Option, + to-value: Option, // ie. true/false + to-entropy: Option<{ + charset: String // ie. 'a-z,A-Z,0-9' len: number - }, + }> } +.. role:: raw-html(raw) + :format: html +:raw-html:`
` + ---- -Examples of actual ``manifest.yaml`` files for existing services: +Examples +-------- + +Actual ``manifest.yaml`` files for existing services: + +LND +^^^ .. code:: yaml compat: v0 - id: c-lightning - version: "0.1.0" - title: c-lightning + id: lnd + version: 0.11.1.1 + title: Lightning Network Daemon description: - short: "The Lightning Node implementation by Blockstream" - long: "A lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol." - release-notes: https://github.com/ElementsProject/lightning/releases/tag/v0.1.0 - ports: - - internal: 8080 - tor: 8080 + short: "A complete implementation of a Lightning Network node by Lightning Labs" + long: "LND fully conforms to the Lightning Network specification (BOLTs). BOLT stands for: Basis of Lightning Technology. In the current state lnd is capable of: creating channels, closing channels, managing all channel states (including the exceptional ones!), maintaining a fully authenticated+validated channel graph, performing path finding within the network, passively forwarding incoming payments, sending outgoing onion-encrypted payments through the network, updating advertised fee schedules, and automatic channel management (autopilot)." + release-notes: https://github.com/lightningnetwork/lnd/releases/tag/v0.11.1-beta + ports: + - internal: 8080 + tor: 8080 + - internal: 9735 + tor: 9735 + - internal: 9911 + tor: 9911 + - internal: 10009 + tor: 10009 image: type: tar - mount: /root/.lightning + mount: /root/.lnd + public: public has-instructions: true - os-version-required: ">=0.2.5" - os-version-recommended: ">=0.2.5" + os-version-required: ">=0.2.8" + os-version-recommended: ">=0.2.8" + install-alert: | + READ CAREFULLY! LND and the Lightning Network are considered beta software. Please use with caution and do not risk more money than you are willing to lose. We encourage frequent backups. If for any reason, you need to restore LND from a backup, your on-chain wallet will be restored, but all your channels will be closed and their funds returned to your on-chain wallet, minus fees. It may also take some time for this process to occur. + uninstall-alert: "READ CAREFULLY! Uninstalling LND will result in permanent loss of data, including its private keys for its on-chain wallet and all channel states. Please make a backup if you have any funds in your on-chain wallet or in any channels. Recovering from backup will restore your on-chain wallet, but due to the architecture of the Lightning Network, your channels cannot be recovered. All your channels will be closed and their funds returned to your on-chain wallet, minus fees. \n" + restore-alert: | + Restoring LND will overwrite its current data, including its on-chain wallet and channels. Any channels opened since the last backup will be forgotten and may linger indefinitely, and channels contained in the backup will be closed and their funds returned to your on-chain wallet, minus fees. assets: [] hidden-service-version: v3 dependencies: - btc-rpc-proxy: - version: "^0.1.0" - optional: Can configure an external bitcoin node. - description: Required for fetching validated blocks. - config: - - rule: '''users.*.name = "c-lightning"' - description: 'Must have an RPC user named "c-lightning"' - suggestions: - - PUSH: - to: 'users' - value: - name: c-lightning - - rule: 'users.[first(item => ''item.name = "c-lightning")].password?' - description: 'RPC user "c-lightning" must have a password' - suggestions: - - SET: - var: 'users.[first(item => ''item.name = "c-lightning")].password' - to-entropy: - charset: 'a-z,A-Z,0-9' - len: 22 - - rule: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks?' - description: 'RPC user "c-lightning" must have "Fetch Blocks" enabled' - suggestions: - - SET: - var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks' - to-value: true + btc-rpc-proxy: + version: "^0.2.4" + optional: Can alternatively configure an external bitcoin node. + description: Used to fetch validated blocks. + config: + - rule: '''users.*.name = "lnd"' + description: 'Must have an RPC user named "lnd"' + suggestions: + - PUSH: + to: "users" + value: + name: lnd + allowed-calls: [] + - SET: + var: 'users.[first(item => ''item.name = "lnd")].password' + to-entropy: + charset: "a-z,A-Z,0-9" + len: 22 + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getinfo"' + description: 'RPC user "lnd" must have "getinfo" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getinfo" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getbestblockhash"' + description: 'RPC user "lnd" must have "getbestblockhash" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getbestblockhash" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "gettxout"' + description: 'RPC user "lnd" must have "gettxout" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "gettxout" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockchaininfo"' + description: 'RPC user "lnd" must have "getblockchaininfo" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getblockchaininfo" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "sendrawtransaction"' + description: 'RPC user "lnd" must have "sendrawtransaction" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "sendrawtransaction" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockhash"' + description: 'RPC user "lnd" must have "getblockhash" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getblockhash" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblock"' + description: 'RPC user "lnd" must have "getblock" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getblock" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockheader"' + description: 'RPC user "lnd" must have "getblockheader" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getblockheader" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "estimatesmartfee"' + description: 'RPC user "lnd" must have "estimatesmartfee" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "estimatesmartfee" + - rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getnetworkinfo"' + description: 'RPC user "lnd" must have "getnetworkinfo" enabled' + suggestions: + - PUSH: + to: 'users.[first(item => ''item.name = "lnd")].allowed-calls' + value: "getnetworkinfo" + - rule: 'users.[first(item => ''item.name = "lnd")].fetch-blocks?' + description: 'RPC user "lnd" must have "Fetch Blocks" enabled' + suggestions: + - SET: + var: 'users.[first(item => ''item.name = "lnd")].fetch-blocks' + to-value: true + bitcoind: + version: "^0.21.0" + optional: Can alternatively configure an external bitcoin node. + description: Used to subscribe to new block events. + config: + - rule: "zmq-enabled?" + description: "Must have an ZeroMQ enabled" + suggestions: + - SET: + var: "zmq-enabled" + to-value: true + +Cups +^^^^ .. code:: yaml diff --git a/source/contributing/services/overview.rst b/source/contributing/services/overview.rst index e7dd4e9..6ea47e1 100644 --- a/source/contributing/services/overview.rst +++ b/source/contributing/services/overview.rst @@ -1,15 +1,43 @@ -.. _service_sdk_overview: +.. _service_package_overview: -******************** -Service SDK Overview -******************** +************************ +Service Package Overview +************************ -Let's start at a high level. What actually is a service, in the technical sense, on the Embassy? +Let's start at a high level. What actually is a service, in a technical sense, on the Embassy? -Each service is an image. An image is a snapshot of linux environment in which an application runs. All service application data is stored in a volume directory. This volume is persisted across updates. The image is immutable: when the service is updated, the image is replaced with the complete new image containing the updated features. +Each service is an image. An image is a snapshot of a linux environment in which an application runs. All service application data is stored in a volume directory. This volume is persisted across updates. The image is immutable: when the service is updated, the image is replaced with the complete new image containing the updated features. -The volume directory (for seeding data into the volume) is typically: ``/root/volumes/``. With the caveat that any files that are in the image at that path will be overwritten. +The volume directory (for seeding data into the volume) is typically: ``/root/volumes/``. -A service is mounted to the OS image. Each service application gets a volume allocated to it by the OS. Within the Docker container that encompasses the service image, a path is specified as to where it should mount on the OS. This path is specified in the :ref:`manifest <_service_manifest>`. +.. important:: + Any files that are in the image at the volume path will be overwritten when a backup restore occurs. -The config spec, config rules, and manifest get bundled into the ``.s9pk`` package when built using `appmgr `_. Thus, each new version release will have these files updated and re-bundled into a new binary. \ No newline at end of file +A service is mounted to the EmbassyOS image. Each service application gets a volume allocated to it by EmbassyOS. Within the Docker container that encompasses the service image, a path is specified as to where it should mount on EmbassyOS. This path is specified in the :ref:`manifest `. + +The config spec, config rules, and manifest get bundled into the ``.s9pk`` package when built using `appmgr `_. Each new version release should include the updated version of these files re-bundled into a new binary. + +.. note:: + Due to tech debt, code in appmgr may reference ``app-id`` instead of ``service-id``. + +Environment Setup +================= + +At minimum, docker, docker-builx, and appmgr are required to package a service for EmbassyOS. + +Recommended Dependencies +------------------------ + +`docker `_ + +`docker-buildx `_ + +`appmgr `_ + +`cargo `_ + +`yq (version 4) `_ + +`make `_ + +`musl `_ diff --git a/source/contributing/services/properties.rst b/source/contributing/services/properties.rst new file mode 100644 index 0000000..3e8a460 --- /dev/null +++ b/source/contributing/services/properties.rst @@ -0,0 +1,15 @@ +.. _service_properties: + +****************** +Service Properties +****************** + +The output of this step is a file titled ``stats.yaml``. This file contains a mapping of the values that will be displayed in the ``Properties`` section in a service's menu. + +.. figure:: /_static/images/service/service_properties.png + :width: 40% + :alt: Service Properties + + Service Properties Tab + +Due to the fact that config variables are only available when the service is running, this file can only be populated at runtime. In services Start9 has wrapped or created, we typically handle this in ``configurator/src/main.rs``. This file is essentially a script that acquires the necessary values at runtime from config (eg. ``/root/.lnd/start9/config.yaml``), and dynamically populating them to the ``stats.yaml`` file, marking each value with the appropriate keys for UI display (ie. masked or copyable). Running the configurator is typically included in the ``docker_entrypoint.sh`` file. \ No newline at end of file diff --git a/source/contributing/services/wrapper.rst b/source/contributing/services/wrapper.rst index 782dadc..3ae297b 100644 --- a/source/contributing/services/wrapper.rst +++ b/source/contributing/services/wrapper.rst @@ -4,17 +4,17 @@ Service Wrapper *************** -Everything you need to build a service. +Each service is bound with a wrapper repository, which contains everything you need to build a service. -Each service is bound with a wrapper repository. The purpose of this repo is: +The purpose of this repo is: -- Denote any dependencies required to run and build the project. -- To define the necessary, ``config_rules.yaml``, ``config_spec.yaml`` and ``manifest.yaml`` options. -- To build the project into the ``.s9pk`` format digestible to the Embassy. -- Link to the source project as a git submodule. -- Define the docker file for running the project on an Embassy. -- Provide documentation for the project, especially user runbook instructions. -- symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root +- Denote any dependencies required to run and build the project +- To define the necessary, ``config_rules.yaml``, ``config_spec.yaml`` and ``manifest.yaml`` options +- To build the project into the ``.s9pk`` format digestible to EmbassyOS +- Link to the source project as a git submodule +- Define the docker file for running the project on EmbassyOS +- Provide documentation for the project, especially user runbook instructions +- symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root, if included File Structure ==============