mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
Dev docs / LAN edits
This commit is contained in:
kn0wmad
BIN
site/source/_static/images/services/synapseconfig.svg
Normal file
BIN
site/source/_static/images/services/synapseconfig.svg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 128 KiB |
@@ -30,13 +30,15 @@ You can check this expansive list if you are in search of ideas: `Awesome Self-H
|
||||
|
||||
What if I don't need a Config in my service?
|
||||
--------------------------------------------
|
||||
Config files can be empty( ``{}`` ), if you do not require config.
|
||||
Config files can be empty( ``{}`` ), if you do not require config. `File Browser <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/config_spec.yaml>`_ is an example of a service with no Config.
|
||||
|
||||
How can my service access the data directory of another service?
|
||||
----------------------------------------------------------------
|
||||
#. Provider service needs to expose datadir to other services on embassy
|
||||
#. Consumer services needs to list the provider service as a dependency AND set a particular config value, stating that it wants data from that particular service
|
||||
|
||||
|
||||
|
||||
The guide says that a Makefile is optional, why is this?
|
||||
--------------------------------------------------------
|
||||
The ``Makefile`` simplifies the development process by putting all your build steps into one place so that you can simply use the ``make`` to build with. A ``Makefile`` is not required however, and you may instead choose to use something like ``nix``, ``bash``, ``perl``, ``python``, or ``ruby`` for your build orchestration.
|
||||
|
||||
@@ -8,7 +8,6 @@ Service Packaging Example
|
||||
:depth: 4
|
||||
:local:
|
||||
|
||||
A rough walkthrough of how to package a service using our example `hello-world-wrapper <https://github.com/Start9Labs/hello-world-wrapper>`_.
|
||||
|
||||
Welcome! The following guide will provide the prerequisites, introduce a brief overview of the packaging process, use an example demonstrating how to package a service, and finally, describe the submission process. This essentially describes how you can take an existing app (or one you have written yourself), and wrap it up into an ``s9pk`` such that it can be added to an EmbassyOS (EOS) Marketplace! The ``s9pk`` is the final product, which is the portable version of a package that is understood by EOS, and can be distributed to any EOS users either directly, or via a Marketplace.
|
||||
|
||||
@@ -47,13 +46,18 @@ Overview
|
||||
Components
|
||||
==========
|
||||
|
||||
Simply, the package is made up of the following parts:
|
||||
1. Image - Each service is running in a Docker image. Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
|
||||
2. Volume - Each service gets a volume, allocated by EOS. This is the filesystem where the service data will be stored and mounted by the container. The volume directory within EOS (for seeding data into the volume) is located at `/embassy-data/package-data/volumes/<service-id>`
|
||||
3. Dependencies - Rules and requirements of your service, which appear as UI elements, such as inputs, toggles, and drop-downs. These are enforced by validations and clear user instructions. EmbassyOS has a unique and powerful system for managing dependencies which allows anyone to have the power of systems administrators without an advanced skillset.
|
||||
4. Manifest - Describes the service and its requirements. This file describes the marketplace listing, installation considerations, configuration and dependency requirements, health checks, backups and additional info.
|
||||
5. Config - EOS makes a service's configuration available to the user in the GUI and must be valid regardless of user skill.
|
||||
6. .s9pk Bundle - The image, manifest, license, icon, and instruction files get bundled into a .s9pk package. Optional additional assets for use with system images can also be bundled. This is the file a user downloads from the Marketplace, at which point EOS uses to unpack assets and install the service.
|
||||
The package is made up of the following parts:
|
||||
|
||||
#. Container Image - Each service is running in a container (typically Docker). Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
|
||||
#. Volume(s) - Each service gets one or more volumes, allocated by EOS. This is the filesystem where the service data will be stored and mounted by the container. The volume directory within EOS (for seeding data into the volume) is located at `/embassy-data/package-data/volumes/<service-id>`
|
||||
#. Dependencies - Rules and requirements of your service, which appear as UI elements, such as inputs, toggles, and drop-downs. These are enforced by validations and clear user instructions. EmbassyOS has a unique and powerful system for managing dependencies which allows anyone to have the power of systems administrators without an advanced skillset.
|
||||
#. Manifest - Describes the service and its requirements. This file describes the marketplace listing, installation considerations, configuration and dependency requirements, health checks, backups and additional info.
|
||||
#. Config - EOS makes a service's configuration available to the user in the GUI and must be valid regardless of user skill.
|
||||
#. Instructions & Docs - Directions for setup, use, external integrations, etc.
|
||||
#. License - The Open Source license of the service wapper.
|
||||
#. Icon - Image used to identify the service in the UI.
|
||||
|
||||
The ``.s9pk`` is the image, manifest, license, icon, and instructions files bundled into a .s9pk package. Optional additional assets for use with system images can also be bundled. This is the file a user downloads from the Marketplace, at which point EOS uses to unpack assets and install the service.
|
||||
|
||||
Check :ref:`here <service_package_overview>` for a detailed overview of package components.
|
||||
|
||||
@@ -66,9 +70,9 @@ Git submodules allow the use of another project while in the working project dir
|
||||
|
||||
Simply run:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: bash
|
||||
|
||||
git submodule add <link_to_source_project>
|
||||
git submodule add <link_to_source_project>
|
||||
|
||||
Example - Hello World
|
||||
---------------------
|
||||
@@ -80,16 +84,16 @@ The commands below assume a Linux development environment with all the recommend
|
||||
Clone the Template Repo and Edit the Manifest
|
||||
=============================================
|
||||
|
||||
1. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
|
||||
#. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
git clone https://github.com/Start9Labs/hello-world-wrapper
|
||||
cd hello-world-wrapper
|
||||
git clone https://github.com/Start9Labs/hello-world-wrapper
|
||||
cd hello-world-wrapper
|
||||
|
||||
2. Edit the ``README.md`` to explain what the service is, what dependencies are required, build/install/contribute instructions, and any other information you'd like.
|
||||
#. Edit the ``README.md`` to explain what the service is, what dependencies are required, build/install/contribute instructions, and any other information you'd like.
|
||||
|
||||
3. Edit the ``manifest`` file. This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style. You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
|
||||
#. Edit the ``manifest`` file. This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style. You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
|
||||
|
||||
Manifest example
|
||||
================
|
||||
@@ -257,72 +261,72 @@ Edit the Dockerfile and Entrypoint
|
||||
|
||||
Next, it's time to edit the ``Dockerfile``. This defines how to build the image for the package by declaring the environment, building stages, and copying any binaries or assets needed to run the service or its health checks to the image filesystem.
|
||||
|
||||
1. We start by importing a base image, in this case Alpine, as recommended.
|
||||
#. We start by importing a base image, in this case Alpine, as recommended.
|
||||
|
||||
.. code:: docker
|
||||
.. code:: docker
|
||||
|
||||
FROM arm64v8/alpine:3.12
|
||||
FROM arm64v8/alpine:3.12
|
||||
|
||||
2. Next we issue some commands, which in this example simply updates repositories, installs required software, and finally creates a directory for nginx.
|
||||
#. Next we issue some commands, which in this example simply updates repositories, installs required software, and finally creates a directory for nginx.
|
||||
|
||||
.. code:: docker
|
||||
.. code:: docker
|
||||
|
||||
RUN apk update
|
||||
RUN apk add tini
|
||||
RUN apk update
|
||||
RUN apk add tini
|
||||
|
||||
RUN mkdir /run/nginx
|
||||
RUN mkdir /run/nginx
|
||||
|
||||
3. Next we will add the cross-compiled binary of ``hello-world`` to ``/usr/local/bin/`` and add the ``docker_entrypoint.sh`` file from the repository. Then we set permissions for ``docker_entrypoint.sh``.
|
||||
#. Next we will add the cross-compiled binary of ``hello-world`` to ``/usr/local/bin/`` and add the ``docker_entrypoint.sh`` file from the repository. Then we set permissions for ``docker_entrypoint.sh``.
|
||||
|
||||
.. code:: docker
|
||||
.. code:: docker
|
||||
|
||||
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
|
||||
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
|
||||
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
|
||||
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
|
||||
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
|
||||
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
|
||||
|
||||
1. Next, we set a working directory, and set the location of the entrypoint. Exposing ports is not necessary for EOS, but its often useful to leave this line for clarity.
|
||||
#. Next, we set a working directory, and set the location of the entrypoint. Exposing ports is not necessary for EOS, but its often useful to leave this line for clarity.
|
||||
|
||||
.. code:: docker
|
||||
.. code:: docker
|
||||
|
||||
WORKDIR /root
|
||||
WORKDIR /root
|
||||
|
||||
EXPOSE 80
|
||||
EXPOSE 80
|
||||
|
||||
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
|
||||
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
|
||||
|
||||
5. Great, let's take a look at our final Embassy Pages ``Dockerfile``:
|
||||
#. Great, let's take a look at our final Hello World ``Dockerfile``:
|
||||
|
||||
.. code:: docker
|
||||
.. code:: docker
|
||||
|
||||
FROM arm64v8/alpine:3.12
|
||||
FROM arm64v8/alpine:3.12
|
||||
|
||||
RUN apk update
|
||||
RUN apk add tini
|
||||
RUN apk update
|
||||
RUN apk add tini
|
||||
|
||||
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
|
||||
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
|
||||
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
|
||||
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
|
||||
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
|
||||
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
|
||||
|
||||
WORKDIR /root
|
||||
WORKDIR /root
|
||||
|
||||
EXPOSE 80
|
||||
EXPOSE 80
|
||||
|
||||
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
|
||||
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
|
||||
|
||||
Docker Entrypoint
|
||||
=================
|
||||
|
||||
1. Okay, let's move on to our ``docker_entrypoint.sh`` file. This is a script that defines what to do when the service starts, and often acts as an init system. It will need to complete any environment setup (such as folder substructure), set any environment variables, and execute the run command. It's also PID 1 in the docker container, so it does all of the signal handling and container exits when it is stopped/exits. If you have built a ``configurator``, this will also need to be called to execute here. Let's take a look at our (extremely basic) Hello World example:
|
||||
#. Okay, let's move on to our ``docker_entrypoint.sh`` file. This is a script that defines what to do when the service starts, and often acts as an init system. It will need to complete any environment setup (such as folder substructure), set any environment variables, and execute the run command. It's also PID 1 in the docker container, so it does all of the signal handling and container exits when it is stopped/exits. If you have built a ``configurator``, this will also need to be called to execute here. Let's take a look at our (extremely basic) Hello World example:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: bash
|
||||
|
||||
#!/bin/sh
|
||||
#!/bin/sh
|
||||
|
||||
export HOST_IP=$(ip -4 route list match 0/0 | awk '{print $3}')
|
||||
export HOST_IP=$(ip -4 route list match 0/0 | awk '{print $3}')
|
||||
|
||||
exec tini hello-world
|
||||
exec tini hello-world
|
||||
|
||||
2. We've defined the file, exported the IP address of the Embassy (host), and run the program.
|
||||
#. We've defined the file, exported the IP address of the Embassy (host), and run the program.
|
||||
|
||||
For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/docker_entrypoint.sh>`_. Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here <https://docs.start9.com/contributing/services/docker.html>`_.
|
||||
|
||||
@@ -346,35 +350,35 @@ Our example ``Makefile`` is again fairly simple for Hello World. Let's take a l
|
||||
all: verify
|
||||
|
||||
verify: hello-world.s9pk $(S9PK_PATH)
|
||||
embassy-sdk verify $(S9PK_PATH)
|
||||
embassy-sdk verify $(S9PK_PATH)
|
||||
|
||||
# embassy-sdk pack errors come from here, check your manifest, config, instructions, and icon
|
||||
hello-world.s9pk: manifest.yaml assets/compat/config_spec.yaml config_rules.yaml image.tar docs/instructions.md $(ASSET_PATHS)
|
||||
embassy-sdk pack
|
||||
embassy-sdk pack
|
||||
|
||||
image.tar: Dockerfile docker_entrypoint.sh hello-world/target/aarch64-unknown-linux-musl/release/hello-world
|
||||
DOCKER_CLI_EXPERIMENTAL=enabled docker buildx build --tag start9/hello-world --platform=linux/arm64 -o type=docker,dest=image.tar .
|
||||
DOCKER_CLI_EXPERIMENTAL=enabled docker buildx build --tag start9/hello-world --platform=linux/arm64 -o type=docker,dest=image.tar .
|
||||
|
||||
hello-world/target/aarch64-unknown-linux-musl/release/hello-world: $(HELLO_WORLD_SRC)
|
||||
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl cargo +beta build --release
|
||||
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl musl-strip target/aarch64-unknown-linux-musl/release/hello-world
|
||||
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl cargo +beta build --release
|
||||
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl musl-strip target/aarch64-unknown-linux-musl/release/hello-world
|
||||
|
||||
manifest.yaml: hello-world/Cargo.toml
|
||||
yq e -i '.version = $(VERSION)' manifest.yaml
|
||||
yq e -i '.version = $(VERSION)' manifest.yaml
|
||||
|
||||
1. The first 5 lines set environment variables.
|
||||
#. The first 5 lines set environment variables.
|
||||
|
||||
2. The next line simply removes the progress of a ``make`` process if it fails.
|
||||
#. The next line simply removes the progress of a ``make`` process if it fails.
|
||||
|
||||
.. code-block:: Makefile
|
||||
|
||||
.DELETE_ON_ERROR:
|
||||
|
||||
3. The ``all`` step is run when the ``make`` command is issued. This attempts the ``verify`` step, which requires that the ``hello-world.s9pk`` must first be built, which first requires the ``image.tar``, and so on. In this case, each step requires the next and each step indicates the necessary existence of a file. If an indicated file has been altered, such as the `docker_entrypoint.sh`, then any step that contains this file will be rebuilt.
|
||||
#. The ``all`` step is run when the ``make`` command is issued. This attempts the ``verify`` step, which requires that the ``hello-world.s9pk`` must first be built, which first requires the ``image.tar``, and so on. In this case, each step requires the next and each step indicates the necessary existence of a file. If an indicated file has been altered, such as the `docker_entrypoint.sh`, then any step that contains this file will be rebuilt.
|
||||
|
||||
4. So the ``.s9pk`` is created with the ``embassy-sdk pack`` command, supplied with the ``manifest``, ``config_spec``, previously created ``image.tar``, and ``instructions.md``. Your project may likely also contain a ``config_rules`` file. Some of these files we have not yet edited, but that will come shortly.
|
||||
#. So the ``.s9pk`` is created with the ``embassy-sdk pack`` command, supplied with the ``manifest``, ``config_spec``, previously created ``image.tar``, and ``instructions.md``. Your project may likely also contain a ``config_rules`` file. Some of these files we have not yet edited, but that will come shortly.
|
||||
|
||||
5. The ``image.tar`` is built below this, the cross-compiled ``hello-world`` source code, and ``manifest`` at the bottom.
|
||||
#. The ``image.tar`` is built below this, the cross-compiled ``hello-world`` source code, and ``manifest`` at the bottom.
|
||||
|
||||
For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
|
||||
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
.. _service_backups:
|
||||
|
||||
===============
|
||||
Service Backups
|
||||
===============
|
||||
=======
|
||||
Backups
|
||||
=======
|
||||
|
||||
Everything within the root of the mounted volume directory will be stored in an EmbassyOS backup. This includes the config (config.yaml) and properties (stats.yaml) files, as well as any other persisted data within the volume directory.
|
||||
Everything within the root of the mounted volume directory will be stored in an EmbassyOS backup. This includes the config (config.yaml) and properties (stats.yaml) files, as well as any other persisted data within the volume directory.
|
||||
|
||||
For restoration purposes, it might be beneficial to ignore certain files or folders. For instance, ignore the shared/public folder that is mounted for dependencies that expose this feature as it causes data inconsistencies on restore.
|
||||
For restoration purposes, it might be beneficial to ignore certain files or folders. For instance, ignore the shared/public folder that is mounted for dependencies that expose this feature as it causes data inconsistencies on restore.
|
||||
|
||||
In this case, create a `.backupignore` file. This file contains a list of relative paths to the ignored files.
|
||||
In this case, create a `.backupignore` file. This file contains a list of relative paths to the ignored files.
|
||||
|
||||
|
||||
Example
|
||||
@@ -16,7 +16,7 @@ Example
|
||||
|
||||
The `btcpayserver wrapper <https://github.com/Start9Labs/btcpayserver-wrapper/blob/master/configurator/src/templates/.backupignore.templates>`_ demonstrates a good use of a backupignore template.
|
||||
|
||||
Ultimately, ``/datadir/.backupignore`` gets populated with:
|
||||
Ultimately, ``/datadir/.backupignore`` gets populated with:
|
||||
|
||||
.. code::
|
||||
|
||||
@@ -26,4 +26,4 @@ Ultimately, ``/datadir/.backupignore`` gets populated with:
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
:raw-html:`<br />`
|
||||
:raw-html:`<br />`
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
.. _service-config:
|
||||
|
||||
============================
|
||||
Service Config Specification
|
||||
============================
|
||||
=====================
|
||||
Service Configuration
|
||||
=====================
|
||||
|
||||
Overview
|
||||
--------
|
||||
Introduction
|
||||
------------
|
||||
|
||||
Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's configuration will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
|
||||
|
||||
@@ -27,11 +27,11 @@ Config Spec
|
||||
-----------
|
||||
|
||||
Overview
|
||||
........
|
||||
========
|
||||
|
||||
.. figure:: /_static/images/services/config.svg
|
||||
.. figure:: /_static/images/services/service5.svg
|
||||
:width: 80%
|
||||
:alt: Bitcoin Config
|
||||
:alt: Synapse 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:
|
||||
|
||||
@@ -40,16 +40,16 @@ This file defines the structure of configuration options your service depends on
|
||||
- Whenever a user edits a service config
|
||||
- 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.
|
||||
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, such as in the Synapse exmple of ``Enable Registration``.
|
||||
|
||||
.. figure:: /_static/images/service/boolean_toggle.png
|
||||
.. figure:: /_static/images/services/synapseconfig.svg
|
||||
: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
|
||||
.....
|
||||
=====
|
||||
|
||||
ConfigSpec Type:
|
||||
|
||||
@@ -60,7 +60,7 @@ ConfigSpec Type:
|
||||
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.
|
||||
|
||||
@@ -92,7 +92,7 @@ The following section contains implementation specifications for the ``config_sp
|
||||
.. _boolean:
|
||||
|
||||
Boolean
|
||||
^^^^^^^
|
||||
.......
|
||||
|
||||
Config value specification denoted as a boolean value. A default value is required.
|
||||
|
||||
@@ -119,7 +119,7 @@ Example:
|
||||
.. _enum:
|
||||
|
||||
Enum
|
||||
^^^^
|
||||
....
|
||||
|
||||
Config value specification denoted as an enum value. Enums values must be a unique set. If no default is provided, ``null`` will be the assumed value.
|
||||
|
||||
@@ -150,7 +150,7 @@ ValueSpec Type:
|
||||
.. _list:
|
||||
|
||||
List
|
||||
^^^^
|
||||
....
|
||||
|
||||
The list type describes an array of values. The values must consist of the same subtype, which can be any of the ValueSpec types available in the EmbassyOS config specification.
|
||||
Lists of any type do not contain the default for each item in list. The list *itself* can have a default. If no default is provided, ``null`` will be the assumed value.
|
||||
@@ -201,7 +201,7 @@ Example:
|
||||
.. _number:
|
||||
|
||||
Number
|
||||
^^^^^^
|
||||
......
|
||||
|
||||
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.
|
||||
|
||||
@@ -235,7 +235,7 @@ Example:
|
||||
.. _object:
|
||||
|
||||
Object Type
|
||||
^^^^^^^^^^^
|
||||
...........
|
||||
|
||||
A nested representation of a ConfigSpec. The object type takes the same structure under the ``spec`` key as a ConfigSpec: a key indicates the field name, and the value denotes the ValueSpec type for that field.
|
||||
|
||||
@@ -303,7 +303,7 @@ Example:
|
||||
.. _string:
|
||||
|
||||
String
|
||||
^^^^^^
|
||||
......
|
||||
|
||||
There are various options for string values. They can optionally be marked as copyable or masked, such as for passwords, which will reflect the UI element display. A pattern, expressed in regex, can be denoted. If it exists, this field requires both the pattern type (ie. Regex) and pattern description (ie. an explanation of the pattern requirements).
|
||||
|
||||
@@ -362,7 +362,7 @@ Examples:
|
||||
.. _pointer:
|
||||
|
||||
Pointer
|
||||
^^^^^^^
|
||||
.......
|
||||
|
||||
The pointer type *points* to a config value on another service installed on EmbassyOS (ie. app subtype) or to the EmbassyOS system (ie. system subtype). When pointing to another service, the ``index`` field indicates the path to the desired config variable.
|
||||
|
||||
@@ -398,7 +398,8 @@ Example:
|
||||
.. _union:
|
||||
|
||||
Union
|
||||
^^^^^
|
||||
.....
|
||||
|
||||
This type describes a necessary dependency. Multiple variants can be expressed to enable the user the option to connect to another service (internal dependency) or outside source (external dependency).
|
||||
|
||||
For example, the Bitcoin Proxy service is united with an instance of Bitcoin. Three variants are defined: internal, external, and a quick connect. In this case, internal refers to the Bitcoin Core instance running on EmbassyOS, and defines the RPC credentials necessary for connecting; external refers to a Bitcoin Core node running on a different device, and defines the RPC credentials necessary for connecting; quick connect refers to yet another method of connecting to a Bitcoin Core node, optimized for convenience.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
.. _service_docker:
|
||||
|
||||
==================
|
||||
Service Dockerfile
|
||||
==================
|
||||
==========
|
||||
Dockerfile
|
||||
==========
|
||||
|
||||
Dockerfile
|
||||
----------
|
||||
@@ -12,7 +12,7 @@ The Dockerfile is responsible for mounting the service application to whatever v
|
||||
|
||||
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.
|
||||
|
||||
For instance:
|
||||
For instance:
|
||||
|
||||
``FROM alpine:3.12``
|
||||
|
||||
@@ -37,4 +37,4 @@ The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Dockerfi
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
:raw-html:`<br />`
|
||||
:raw-html:`<br />`
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
.. _service_instructions:
|
||||
|
||||
====================================
|
||||
Service Instructions & Documentation
|
||||
====================================
|
||||
===================
|
||||
Instructions & Docs
|
||||
===================
|
||||
|
||||
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
|
||||
.. figure:: /_static/images/services/service-instruct.svg
|
||||
:width: 80%
|
||||
:alt: Bitcoin Instructions
|
||||
:alt: Embassy Pages Instructions
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
.. _service_makefile:
|
||||
|
||||
================
|
||||
Service Makefile
|
||||
================
|
||||
========
|
||||
Makefile
|
||||
========
|
||||
|
||||
.. note::
|
||||
|
||||
*This file is optional*
|
||||
.. note:: *This file is optional*
|
||||
|
||||
A Makefile serves as a convenience for outlining the build. This helps streamline additional developer contributions to the project. Please reference the GNU `documentation <https://www.gnu.org/software/make/manual/html_node/Introduction.html>`_ for implementation details.
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
.. _service_manifest:
|
||||
|
||||
================
|
||||
Service Manifest
|
||||
================
|
||||
========
|
||||
Manifest
|
||||
========
|
||||
|
||||
Overview
|
||||
--------
|
||||
@@ -82,7 +82,7 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
|
||||
# A map of dependent services, see below for more details
|
||||
dependencies: Dependencies
|
||||
|
||||
.. _dependencies:
|
||||
.. _dependencies-spec:
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
@@ -122,7 +122,7 @@ The service ``btc-rpc-proxy`` is a dependency of the service ``c-lightning``. ``
|
||||
Dependency config rules are processed in order.
|
||||
|
||||
Type definitions
|
||||
................
|
||||
================
|
||||
|
||||
Types for ``manifest.yaml`` fields:
|
||||
|
||||
@@ -175,12 +175,12 @@ Types for ``manifest.yaml`` fields:
|
||||
:raw-html:`<br />`
|
||||
|
||||
Examples
|
||||
........
|
||||
========
|
||||
|
||||
Actual ``manifest.yaml`` files for existing services:
|
||||
|
||||
LND
|
||||
^^^
|
||||
...
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
@@ -313,7 +313,7 @@ LND
|
||||
to-value: true
|
||||
|
||||
Cups
|
||||
^^^^
|
||||
....
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
|
||||
@@ -15,7 +15,7 @@ First, let's get your system setup with the necessary software dependencies.
|
||||
Environment Setup
|
||||
-----------------
|
||||
|
||||
At minimum, ``docker``, ``docker-buildx``, and ``appmgr`` are required. The rest of the recommendations serve to optimize the build process.
|
||||
At minimum, ``docker``, ``docker-buildx``, and ``embassy-sdk`` are required. The rest of the recommendations serve to optimize the build process.
|
||||
|
||||
Recommended Dependencies
|
||||
========================
|
||||
@@ -24,7 +24,7 @@ Recommended Dependencies
|
||||
|
||||
`docker-buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
|
||||
|
||||
`appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_
|
||||
`embassy-sdk <https://github.com/Start9Labs/embassy-os/tree/master/backend>`_
|
||||
|
||||
`cargo <https://doc.rust-lang.org/cargo/>`_
|
||||
|
||||
@@ -46,26 +46,25 @@ Because the service ultimately runs on a Raspberry Pi, the created Docker image
|
||||
|
||||
The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
|
||||
|
||||
Volume
|
||||
======
|
||||
Volumes
|
||||
=======
|
||||
|
||||
Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates.
|
||||
Each service application gets one or more volumes allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates.
|
||||
|
||||
The volume directory (for seeding data into the volume) is typically: ``/root/volumes/<service-id>``.
|
||||
The default volume directory (for seeding data into the volume) is typically: ``/root/volumes/<service-id>``.
|
||||
|
||||
.. warning::
|
||||
Any files that are in the image at the volume path will be overwritten when a backup restore occurs.
|
||||
.. warning:: Any files that are in the image at the volume path will be overwritten when a backup restore occurs.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat.
|
||||
When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this task.
|
||||
|
||||
Some other personal server products aimed at non-technical individuals tackle this problem by simply hard coding dependencies. Since EmbassyOS is a platform for running all open-source, self-hosted software, it is not possible to hard code every possible service, service dependency, and service dependency configuration forever. Instead, Start9 built a new, unprecedented operating system that touts a generalized, intuitive approach to dependency management and service configuration. EmbassyOS enables users to easily and selectively install, uninstall, and update any service they want without getting stuck in dependency hell.
|
||||
|
||||
This may sound cool or neat, but it is more than that: *it’s novel*. This has never been done before.
|
||||
This may sound cool or neat, but it is more than that: *it's novel*. This has never been done before.
|
||||
|
||||
The key to making the system work is a new, domain-specific-language (DSL) and set of standards that are used by developers to define the rules and requirements of their services. Run in the context of EmbassyOS, these rules and requirements appear as simple UI elements, such as inputs, toggles, and drop downs, and they are enforced by validations and clear user instructions. Using this system, what previously required involved time and expertise, can now be done by anyone in a matter of seconds.
|
||||
The key to making the system work is a new, domain-specific-language (DSL) and set of standards that are used by developers to define the rules and requirements of their services. Run in the context of EmbassyOS, these rules and requirements appear as simple UI elements, such as inputs, toggles, and drop downs, and they are enforced by validations and clear user instructions. Using this system, what previously required serious time and expertise, can now be done by anyone in a matter of seconds.
|
||||
|
||||
This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <service-dependencies>` key in the service manifest.
|
||||
|
||||
@@ -82,7 +81,7 @@ Each time a service is updated, the manifest should be updated to include the ne
|
||||
|
||||
For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/blob/master/manifest.yaml#L28>`_ around restoration since data will be overwritten.
|
||||
|
||||
There is nothing you need to do as a developer to enable the service to run over Tor. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated and an Nginx server configured (if a client application) when the service is installed. Just define which version of Tor your service needs in this manifest file!
|
||||
There is nothing you need to do as a developer to enable the service to run over Tor/LAN. This is *completely* handled by EmbassyOS - a Tor and LAN address will be automatically generated and an Nginx server configured (if a client application) when the service is installed.
|
||||
|
||||
Config
|
||||
======
|
||||
@@ -94,7 +93,7 @@ With EmbassyOS, this means a service wrappers' configuration requires a particul
|
||||
.s9pk Bundle
|
||||
============
|
||||
|
||||
The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_. Each new version release should include the updated version of these files re-bundled into a new binary. This is the file that will be downloaded from the marketplace. Upon user initiation, EmbassyOS then un-packages and installs the service.
|
||||
The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using embassy-sdk <https://github.com/Start9Labs/embassy-os/tree/master/backend>`_. Each new version release should include the updated version of these files re-bundled into a new binary. This is the file that will be downloaded from the marketplace. When the user clicks the service's "Install" button, EmbassyOS unpacks and installs the service.
|
||||
|
||||
Hello World Example
|
||||
===================
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
.. _service_properties:
|
||||
|
||||
==================
|
||||
Service Properties
|
||||
==================
|
||||
==========
|
||||
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
|
||||
.. figure:: /_static/images/services/props.svg
|
||||
:width: 80%
|
||||
:alt: Service Properties
|
||||
|
||||
@@ -22,4 +22,4 @@ A good example of the configurator producing the ``stats.yaml`` file can be foun
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
:raw-html:`<br />`
|
||||
:raw-html:`<br />`
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
.. _service_wrapper:
|
||||
|
||||
===============
|
||||
Service Wrapper
|
||||
===============
|
||||
=======
|
||||
Wrapper
|
||||
=======
|
||||
|
||||
Each service is bound with a wrapper repository, which contains everything you need to build a service.
|
||||
|
||||
@@ -39,4 +39,4 @@ Submodule
|
||||
|
||||
`Git submodules <https://www.git-scm.com/book/en/v2/Git-Tools-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 its context is available.
|
||||
|
||||
Run ``git submodule add <link_to_source_project>``
|
||||
Run ``git submodule add <link_to_source_project>``
|
||||
|
||||
@@ -26,10 +26,12 @@ If you are running Android 12+ (not yet available on Calyx/Graphene), you can se
|
||||
|
||||
.. figure:: /_static/images/ssl/android/droidLAN0.svg
|
||||
:width: 30%
|
||||
Install certificate
|
||||
:alt: Install certificate
|
||||
|
||||
#. To setup in Firefox, enter ``about:config`` in URL bar, search for "security.enterprise_roots.enabled", and set to ``true``
|
||||
|
||||
.. figure:: /_static/images/ssl/android/droidLAN1.svg
|
||||
:width: 30%
|
||||
Firefox about:config
|
||||
:alt: Firefox about:config
|
||||
|
||||
#. That's it! You may now browse the ``.local`` addresses on your Embassy.
|
||||
|
||||
@@ -73,5 +73,3 @@ iOS
|
||||
|
||||
#. Test that this process worked successfully by navigating to the LAN address provided from one of the locations listed under Step 1 at the top of this page. You should not see warnings about the security of this site in your browser (if you do, setup was not successful).
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -37,7 +37,7 @@ Hardware: Components
|
||||
|
||||
.. caution:: If you prefer to use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
|
||||
|
||||
#. A `16GB microSD card <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (no need for bigger). If you have ABSOLUTELY NO data to migrate, you may choose to re-use the card already in your Embassy.
|
||||
#. A `16GB microSD card <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (no need for bigger). If you have ABSOLUTELY NO data to migrate (from an Embassy v0.2.x), you may choose to re-use the card already in your Embassy.
|
||||
#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
|
||||
#. Ethernet cable
|
||||
#. MicroSD → USB adapter (or you may have a microSD port on your computer)
|
||||
|
||||
Reference in New Issue
Block a user