mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 02:11:55 +00:00
copy updates
This commit is contained in:
Lucy Cifferello
@@ -20,15 +20,14 @@ For instance:
|
||||
|
||||
``FROM arm32v7/golang:alpine``
|
||||
|
||||
We recommended using ``alpine`` since it produces the smallest image. We try to keep the image under 100MB when possible.
|
||||
|
||||
Entry-point
|
||||
===========
|
||||
|
||||
File specified as: ``docker_entrypoint.sh``
|
||||
The ``docker_entrypoint.sh`` defines what to do when the service application starts.
|
||||
|
||||
This file defines what to do when the service application starts.
|
||||
|
||||
It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands on EmbassyOS.
|
||||
It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands for EmbassyOS.
|
||||
|
||||
Example
|
||||
=======
|
||||
|
||||
@@ -12,6 +12,8 @@ If an ``instructions.md`` file is included, this markdown formatted file will be
|
||||
:width: 80%
|
||||
:alt: Bitcoin Instructions
|
||||
|
||||
The `bitcoind wrapper <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs>`_ demonstrates a good use of instructions and external integrations.
|
||||
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Welcome! If you are here, you are interested in becoming part of the mission to
|
||||
|
||||
A service in this context is any open source project that has been bundled into the appropriate format to run on EmbassyOS. By configuring and packaging a project according to this guide, it can be installed on EmbassyOS with no command line or technical expertise required. This opens up an entire platform for self-hosted software to run independent of third parties in a completely private and sovereign way for all individuals.
|
||||
|
||||
This guide is technical, but breaks down the steps for deployment. If you have any feedback or questions concerning this guide, please don't hesitate to `reach out <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_.
|
||||
This guide is technical, but breaks down the steps for deployment. If you have any feedback or questions concerning this guide, please don't hesitate to `reach out <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ or submit a pull request with alterations.
|
||||
|
||||
To start, you will need to acquire EmbassyOS for testing the packaged service. This can be done by:
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Service Makefile
|
||||
|
||||
*This file is optional*
|
||||
|
||||
A Makefile serves as a convenience for building and for additional developer contributions to your project. Please reference the GNU `documentation <https://www.gnu.org/software/make/manual/html_node/Introduction.html>`_ for implementation details.
|
||||
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.
|
||||
|
||||
An alternative to using ``make`` is to use the `nix <https://nixos.wiki/wiki/Nix>`_ specification.
|
||||
|
||||
@@ -15,7 +15,7 @@ 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
|
||||
- Package ``config.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoke ``appmgr``.
|
||||
- Package ``config_rules.yaml``, ``config_spec.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoking ``appmgr``.
|
||||
|
||||
Example
|
||||
=======
|
||||
|
||||
@@ -13,11 +13,11 @@ This file describes the service and it's requirements. It is used to:
|
||||
- denote any installation considerations
|
||||
- define dependency requirements
|
||||
|
||||
Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information about the particularities of the service.
|
||||
Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information.
|
||||
|
||||
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 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 set up Tor for running a service. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated when the service is installed. Just define the port and which version of Tor the service needs in this manifest file! You do, however, need to ensure the service is in fact capable of running over Tor.
|
||||
|
||||
The manifest is also responsible for outlining service :ref:`dependencies <dependencies>`. By defining rules using the :ref:`EmbassyOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. EmbassyOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
|
||||
|
||||
|
||||
@@ -16,19 +16,19 @@ At minimum, ``docker``, ``docker-buildx``, and ``appmgr`` are required. The rest
|
||||
Recommended Dependencies
|
||||
------------------------
|
||||
|
||||
`docker <https://docs.docker.com/get-docker>`_
|
||||
`docker <https://docs.docker.com/get-docker>`_
|
||||
|
||||
`docker-buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
|
||||
`docker-buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
|
||||
|
||||
`appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_
|
||||
`appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_
|
||||
|
||||
`cargo <https://doc.rust-lang.org/cargo/>`_
|
||||
`cargo <https://doc.rust-lang.org/cargo/>`_
|
||||
|
||||
`yq (version 4) <https://mikefarah.gitbook.io/yq>`_
|
||||
`yq (version 4) <https://mikefarah.gitbook.io/yq>`_
|
||||
|
||||
`make <https://www.gnu.org/software/make/>`_
|
||||
`make <https://www.gnu.org/software/make/>`_
|
||||
|
||||
`musl <https://github.com/Start9Labs/rust-musl-cross>`_
|
||||
`musl <https://github.com/Start9Labs/rust-musl-cross>`_
|
||||
|
||||
Package Components
|
||||
==================
|
||||
@@ -54,7 +54,7 @@ The volume directory (for seeding data into the volume) is typically: ``/root/vo
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from the 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 feat.
|
||||
|
||||
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.
|
||||
|
||||
@@ -77,19 +77,19 @@ 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 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. 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!
|
||||
|
||||
Config
|
||||
------
|
||||
|
||||
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 :ref:`configuration <service_config>` 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.
|
||||
|
||||
With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and dependency management.
|
||||
With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and configuration dependencies.
|
||||
|
||||
.s9pk Bundle
|
||||
------------
|
||||
|
||||
The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/appmgr>`_. Each new version release should include the updated version of these files re-bundled into a new binary.
|
||||
The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/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.
|
||||
|
||||
Hello World Example
|
||||
-------------------
|
||||
|
||||
@@ -7,14 +7,14 @@ 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%
|
||||
:width: 80%
|
||||
: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.
|
||||
|
||||
A good example of the a configurator producing the ``stats.yaml`` file can be found `here <https://github.com/Start9Labs/btc-rpc-proxy-wrapper/blob/master/configurator/src/main.rs>`_.
|
||||
A good example of the configurator producing the ``stats.yaml`` file can be found `here <https://github.com/Start9Labs/lnd-wrapper/blob/master/configurator/src/main.rs`_.
|
||||
|
||||
.. role:: raw-html(raw)
|
||||
:format: html
|
||||
|
||||
@@ -41,15 +41,15 @@ The project structure should be used as a model:
|
||||
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.
|
||||
`Git sub-modules <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 it's context is available.
|
||||
|
||||
Run ``git submodule add <link_to_source_project>``
|
||||
|
||||
For reference: `git-submodules <https://www.git-scm.com/book/en/v2/Git-Tools-Submodules>`_
|
||||
|
||||
Assets
|
||||
======
|
||||
|
||||
*This section is being deprecated in favor of baking assets into the Docker image, and moved into the mountpoint at runtime if necessary*
|
||||
|
||||
Whenever a service is stopped, any file that is not contained within in the ``/assets`` directory will be cleared from memory. Any unsaved changes will be reverted. This folder acts as a persistance storage container.
|
||||
|
||||
In this folder belongs any assets that are unique configurations to your service. For instance, bitcoind's ``.conf`` file is saved here.
|
||||
|
||||
Reference in New Issue
Block a user