diff --git a/source/contributing/services/config.rst b/source/contributing/services/config.rst new file mode 100644 index 0000000..96da890 --- /dev/null +++ b/source/contributing/services/config.rst @@ -0,0 +1,33 @@ +.. _service_config: + +********************** +Service Configurations +********************** + + +Config Spec +=========== + +.. code:: yaml + + --- + password: + type: string + nullable: false + name: "Password" + description: "The password for connecting to the server." + default: + charset: "a-k,m-z,2-9" + len: 20 + pattern: '^[^\n"]*$' + patternDescription: "Must not contain newline or quote characters." + +Config Rules +============ + +.. code:: yaml + + --- + - rule: 'rpc.enable? OR !(''advanced.pruning.mode = "manual")' + description: "RPC must be enabled for manual pruning." + diff --git a/source/contributing/services/dependencies.rst b/source/contributing/services/dependencies.rst new file mode 100644 index 0000000..edf9c37 --- /dev/null +++ b/source/contributing/services/dependencies.rst @@ -0,0 +1,5 @@ +.. _service_dependencies: + +******************** +Service Dependencies +******************** \ No newline at end of file diff --git a/source/contributing/services/docker.rst b/source/contributing/services/docker.rst new file mode 100644 index 0000000..3b41a38 --- /dev/null +++ b/source/contributing/services/docker.rst @@ -0,0 +1,13 @@ +.. _service_docker: + +****************** +Service DockerFile +****************** + +``docker_entrypoint.sh`` + +A bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. + +```Dockerfile``` + +Declares the environment and building stages for the project. \ No newline at end of file diff --git a/source/contributing/services/index.rst b/source/contributing/services/index.rst new file mode 100644 index 0000000..cee42ab --- /dev/null +++ b/source/contributing/services/index.rst @@ -0,0 +1,17 @@ +.. _service_sdk: + +********************************* +Services Software Development Kit +********************************* + + +The `File Browser wrapper repository `_ should be used as an example. + +.. toctree:: + :maxdepth: 2 + + dependencies + config + manifest + docker + wrapper \ No newline at end of file diff --git a/source/contributing/services/manifest.rst b/source/contributing/services/manifest.rst new file mode 100644 index 0000000..4884214 --- /dev/null +++ b/source/contributing/services/manifest.rst @@ -0,0 +1,109 @@ +.. _service_manifest: + +**************** +Service Manifest +**************** + +Types: + +Manifest +.. code:: rust + + id: String + version: semver::Version + title: String + description: Description + release_notes: String + has_instructions: bool + os_version_required: semver::VersionReq + os_version_recommended: semver::VersionReq + ports: Vec + image: ImageConfig + mount: PathBuf + assets: Vec + hidden_service_version: HiddenServiceVersion + dependencies: Dependencies + extra: LinearMap + +Version +.. code:: rust + +VersionReq +.. code:: rust + +ImageConfig + +pub enum ImageConfig { + Tar, +} + + +#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)] +pub struct Asset { + pub src: PathBuf, + pub dst: PathBuf, + pub overwrite: bool, +} + +pub struct Description { + pub short: String, + pub long: String, +} + +pub struct PortMapping { + pub internal: u16, + pub tor: u16, +} + +pub enum HiddenServiceVersion { + V1, + V2, + V3, +} + +pub struct Dependencies(pub LinearMap); + +#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)] +pub struct DepInfo { + pub version: VersionReq, + pub optional: Option, + pub description: Option, + #[serde(default)] + pub config: Vec, +} + +---- + +Example ``manifest.yaml``: + +.. 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 diff --git a/source/contributing/services/wrapper.rst b/source/contributing/services/wrapper.rst new file mode 100644 index 0000000..a5c6eb6 --- /dev/null +++ b/source/contributing/services/wrapper.rst @@ -0,0 +1,47 @@ +.. _service_wrapper: + +*************** +Service Wrapper +*************** + +Each service is bound with a wrapper repository. 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 + +File Structure +============== + +The project structure should be used as a model: + +.. code-block:: bash + + ├── Dockerfile + ├── Makefile + ├── README.md + ├── assets + │ ├── httpd.conf + │ └── httpd.conf.template + ├── config_rules.yaml + ├── config_spec.yaml + ├── + ├── docker_entrypoint.sh + ├── docs + │ └── instructions.md + ├── instructions.md -> docs/instructions.md (symlink) + └── manifest.yaml + +Submodule +========== + +Git submodules allow use of another project while in the working project directory. Setting up this feature enables linking of the source service repository so that it's context is available. + +Run ``git submodule add `` + +For reference: `git-submodules `_ +