documentation/source/contributing/services/manifest.rst

.. _service_manifest:

****************
Service Manifest
****************

This file describes the service and it's requirements. Important to note is the dependencies key, which contains rules for optional or required other services that are depended on to successfully run the service at hand. 

Formatting: 
    - Serialization language:``.yaml``
    - Case style: ``kebab-case``

Below are the types and sub-type definitions, with necessary elaborations:

Manifest
.. code:: yaml

    # manifest version compatibility ie. v0 (this is currently the only option)
    compat: v0
    # service id, used for uniqueness and BE identification ie. bitcoind
    id: String
    # semantic version for the release
    version: String
    # display name of service
    title: String
    # an object containing a short and long description of the service. TODO character lengths
    description:
        short: String
        long: String
    # a link to the release tag notes in GitHub, or a short description TODO character length
    release_notes: String
    # denoting the existence of instructions.md
    has_instructions: Boolean
    # required version of EmbassyOS to run service
    os_version_required: VersionReq
    # recommended version of EmbassyOS to run service
    os_version_recommended: VersionReq
    # a list of objects of ports to run the service on localhost and tor
    ports:
        - internal: String
          tor: String
    # currently only tar is supported
    image:
        type: String 
    # path to mount the image on the volume, ie: /root/bitcoind
    mount: String
    # 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
    assets:
      - src: String TODO confirm type
        dst: String TODO confirm type
        overwrite: Boolean
    # version of tor support, eg. v1, v2, v3
    hidden_service_version: String
    # A map of dependent services, see below for more details
    dependencies: Dependencies

Version
.. code:: yaml

    @aiden define type if more than string

VersionReq
.. code:: yaml

    @aiden define type if more than string


Dependencies
------------

.. code:: typescript

    interface Dependencies [{
        serviceId: DepInfo
    }]

    interface DepInfo {
        version: String -- TODO correct for VersionReq?,
        optional?: String,
        description?: String,
        config: [
            entry: {
                rule: ConfigRule,
                description: String,
            },
            suggestions: [{
                condition?: ConfigRule,
                variant: SuggestionVariant,
            }],
        ],
    }

    interface SuggestionVariant {
        SET: {
            var: String,
            to: SetVariant,
        },
        DELETE: {
            src: String,
        },
        PUSH: {
            to: String,
            value: Value, @aiden define Value
        },
    }

    interface SetVariant {
        to: string,
        to-value: Value,
        to-entropy: {
            charset: String // 'a-z,A-Z,0-9'
            len: number
        },
    }

----

Examples:

.. code:: yaml

    compat: v0
    id: c-lightning
    version: "0.1.0"
    title: c-lightning
    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
    image:
    type: tar
    mount: /root/.lightning
    has-instructions: true
    os-version-required: ">=0.2.5"
    os-version-recommended: ">=0.2.5"
    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

.. code:: yaml

    compat: v0
    id: cups
    version: "0.3.6"
    title: "Cups Messenger"
    description:
    short: "Real private messaging"
    long: "Cups is a private, self-hosted, peer-to-peer, Tor-based, instant messenger. Unlike other end-to-end encrypted messengers, with Cups on the Embassy there are no trusted third parties."
    release-notes: |
    Features
        - Adds instructions defined by EmbassyOS 0.2.4 instructions feature
    ports:
        - internal: 59001
            tor: 59001
        - internal: 80
            tor: 80
    image:
    type: tar
    mount: /root
    has-instructions: true
    os-version-required: ">=0.2.4"
    os-version-recommended: ">=0.2.4"
    assets:
        - src: httpd.conf
            dst: "."
            overwrite: true
        - src: www
            dst: "."
            overwrite: true
    hidden-service-version: v3