mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-30 04:01:59 +00:00
Dev docs / LAN edits
This commit is contained in:
kn0wmad
@@ -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>``
|
||||
|
||||
Reference in New Issue
Block a user