mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
Update flashing guide for all platforms
This commit is contained in:
kn0wmad
@@ -6,7 +6,7 @@ Backups
|
||||
|
||||
Backups are defined by the service developer in the backups section of the Manifest. By default, this action is a command executed within a Docker container.
|
||||
|
||||
EmbassyOS provides a system utility for creating backups. This system utility is the `duplicity <https://en.wikipedia.org/wiki/Duplicity_(software)>`_ library that is run inside the Docker image entitled _compat_.
|
||||
embassyOS provides a system utility for creating backups. This system utility is the `duplicity <https://en.wikipedia.org/wiki/Duplicity_(software)>`_ library that is run inside the Docker image entitled _compat_.
|
||||
|
||||
The path to be backed up can be specified in the Manifest. In the create backup example below, it is the last argument:
|
||||
|
||||
|
||||
@@ -4,9 +4,9 @@
|
||||
Compat Image
|
||||
============
|
||||
|
||||
With the release of EmbassyOS v0.3.0, system utility Docker images are preloaded for service packager convenience.
|
||||
With the release of embassyOS v0.3.0, system utility Docker images are preloaded for service packager convenience.
|
||||
|
||||
The ``Compat`` image is a backwards compatible Docker image that hosts EmbassyOS features used in the v0.2.x series. It was created as a convenience for service packagers to help migrate their service configurations from 0.2.x to 0.3.0.
|
||||
The ``Compat`` image is a backwards compatible Docker image that hosts embassyOS features used in the v0.2.x series. It was created as a convenience for service packagers to help migrate their service configurations from 0.2.x to 0.3.0.
|
||||
|
||||
It exposes functionality to make use of:
|
||||
|
||||
|
||||
@@ -7,9 +7,9 @@ Config Spec
|
||||
Introduction
|
||||
============
|
||||
|
||||
Most self-hosted applications require the user to tell the application 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 the services' 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.
|
||||
Most self-hosted applications require the user to tell the application 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 the services' 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.
|
||||
|
||||
With EmbassyOS, this means a services' configuration requires a file to define the particular format 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 services' configuration requires a file to define the particular format to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and dependency management.
|
||||
|
||||
This file defines the *structure* of the service's native config and should be curated according to the ``ConfigSpec`` type, which is a detailed mapping of the configuration options with acceptable values, defined patterns, and defaults.
|
||||
|
||||
@@ -150,7 +150,7 @@ Example
|
||||
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.
|
||||
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.
|
||||
|
||||
Range is loosely based off mathematical range syntax, with infinity replaced with ``*``:
|
||||
@@ -358,7 +358,7 @@ Examples
|
||||
Pointer
|
||||
--------
|
||||
|
||||
The pointer type *points* to a config value on another service installed on EmbassyOS (ie. package subtype) or to the EmbassyOS system (ie. system subtype). When pointing to another service, the ``selector`` field indicates the path to the desired config variable.
|
||||
The pointer type *points* to a config value on another service installed on embassyOS (ie. package subtype) or to the embassyOS system (ie. system subtype). When pointing to another service, the ``selector`` field indicates the path to the desired config variable.
|
||||
|
||||
.. code-block::
|
||||
:caption: ValueSpec Type
|
||||
@@ -396,7 +396,7 @@ 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.
|
||||
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.
|
||||
|
||||
Default is required and corresponds to one of the variants.
|
||||
|
||||
|
||||
@@ -9,18 +9,18 @@ Background
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Context
|
||||
-------
|
||||
|
||||
Many services depend on other libraries and services on EmbassyOS (such as Bitcoin), sometimes even a particular version of those services. These need to be specified by the developers so that EmbassyOS can handle installing these dependencies under the hood.
|
||||
Many services depend on other libraries and services on embassyOS (such as Bitcoin), sometimes even a particular version of those services. These need to be specified by the developers so that embassyOS can handle installing these dependencies under the hood.
|
||||
|
||||
Requirement
|
||||
-----------
|
||||
@@ -38,7 +38,7 @@ Only the type of requirement must be defined. Requirement types include:
|
||||
Advanced Configuration
|
||||
----------------------
|
||||
|
||||
If a dependency requires a more advanced configuration, rule checks and auto configurations can be implemented. These functions utilize a preloaded Docker image within EmbassyOS entitled _compat_. This system utility provides the mechanisms for checking dependency configuration compatibility by providing a file with the defined rules as input.
|
||||
If a dependency requires a more advanced configuration, rule checks and auto configurations can be implemented. These functions utilize a preloaded Docker image within embassyOS entitled _compat_. This system utility provides the mechanisms for checking dependency configuration compatibility by providing a file with the defined rules as input.
|
||||
|
||||
In this case, each dependency contains a set of rules that need to be fulfilled as true if the dependency is to be properly installed. The "config rules" here are for auto-configuring dependencies - the action defined by the rule will be executed if the service is auto configured with defaults during initial setup. This simplifies and streamlines the user experience. The interface should provide suggestions for the behavior if the denoted rule cannot be met with previous configurations.
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ Each service boils down to a Docker image. We're not going to dive into Docker s
|
||||
|
||||
The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
|
||||
|
||||
When installed, the service image is mounted to the EmbassyOS image. This path is defined in the :ref:`manifest <service_manifest>` configuration file:
|
||||
When installed, the service image is mounted to the embassyOS image. This path is defined in the :ref:`manifest <service_manifest>` configuration file:
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
@@ -43,12 +43,12 @@ When installed, the service image is mounted to the EmbassyOS image. This path i
|
||||
io-format: yaml
|
||||
...
|
||||
|
||||
In EmbassyOS, the mount specified in the Manifest gets bound to ``/embassy-data/package-data/volumes/main/<service-id>``.
|
||||
In embassyOS, the mount specified in the Manifest gets bound to ``/embassy-data/package-data/volumes/main/<service-id>``.
|
||||
|
||||
Volumes
|
||||
-------
|
||||
|
||||
Volumes are the mechanism for persisting data generated by and used by Docker containers. In EmbassyOS, services can declare as one or many volumes in the Manifest:
|
||||
Volumes are the mechanism for persisting data generated by and used by Docker containers. In embassyOS, services can declare as one or many volumes in the Manifest:
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Instructions
|
||||
|
||||
Within each wrapper repository, a file should exist that includes instructions for a service. This file should include any pertinent documentation, instructions, external integrations, or other details about the service that users or developers might find relevant.
|
||||
|
||||
This markdown formatted file will be rendered in the "Instructions" section within the service page on EmbassyOS:
|
||||
This markdown formatted file will be rendered in the "Instructions" section within the service page on embassyOS:
|
||||
|
||||
.. figure:: /_static/images/services/service-instruct.png
|
||||
:width: 80%
|
||||
|
||||
@@ -30,7 +30,7 @@ Terms:
|
||||
|
||||
**Procedure**: A procedure is run during times that we would like to do an operation. An operation would include actions such as getting or setting a service's configuration file.
|
||||
|
||||
**Effects**: A TypeScript object that is used to interact with EmbassyOS. See the `full definition here <https://deno.land/x/embassyd_sdk@v0.3.1.0.5/types.ts>`__.
|
||||
**Effects**: A TypeScript object that is used to interact with embassyOS. See the `full definition here <https://deno.land/x/embassyd_sdk@v0.3.1.0.5/types.ts>`__.
|
||||
|
||||
This new process enabled faster service configuration operations. Previously, Docker was used to preform these actions; however, Docker containers took a long time to spin up.
|
||||
|
||||
@@ -73,7 +73,7 @@ How to Setup
|
||||
set:
|
||||
type: script
|
||||
|
||||
4. Fill in the todos in the above template to match the expected Effect parameter defined by the `exported type <https://deno.land/x/embassyd_sdk@v0.3.1.0.3/types.ts#L32>`_. This type describes how to call functions that interact with EmbassyOS.
|
||||
4. Fill in the todos in the above template to match the expected Effect parameter defined by the `exported type <https://deno.land/x/embassyd_sdk@v0.3.1.0.3/types.ts#L32>`_. This type describes how to call functions that interact with embassyOS.
|
||||
5. In the build process for packaging the final s9pk, include the following step. **The location of the js is important, and can't be changed**. It must exist at `scripts/embassy.js` in the root of the project's wrapper repository.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
@@ -17,9 +17,9 @@ This file describes the service and it's requirements. It is used to:
|
||||
|
||||
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.
|
||||
|
||||
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 an interface with a tor config in the Manifest file. You do, however, need to ensure the service is in fact capable of running over Tor.
|
||||
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 an interface with a tor config in the 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-spec>`. 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!
|
||||
The Manifest is also responsible for outlining service :ref:`dependencies <dependencies-spec>`. 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!
|
||||
|
||||
Formatting
|
||||
----------
|
||||
@@ -38,7 +38,7 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
|
||||
id: String
|
||||
# A human readable service title
|
||||
title: String
|
||||
# Service version - accepts up to four digits, where the last confirms to revisions necessary for EmbassyOS - see documentation: https://github.com/Start9Labs/emver-rs. This value will change with each release of the service.
|
||||
# Service version - accepts up to four digits, where the last confirms to revisions necessary for embassyOS - see documentation: https://github.com/Start9Labs/emver-rs. This value will change with each release of the service.
|
||||
version: Number
|
||||
# Release notes for the update - can be a string, paragraph or URL
|
||||
release-notes: String
|
||||
@@ -54,9 +54,9 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
|
||||
marketing-site: String
|
||||
# The series of commands to build the project into an s9pk for arm64/v8. In this case we are using a Makefile with the simple build command "make".
|
||||
build: List<String>
|
||||
# Minimum required version of EmbassyOS
|
||||
# Minimum required version of embassyOS
|
||||
min-os-version: Number
|
||||
# Human readable descriptors for the service. These are used throughout the EmbassyOS user interface, primarily in the marketplace.
|
||||
# Human readable descriptors for the service. These are used throughout the embassyOS user interface, primarily in the marketplace.
|
||||
description:
|
||||
# This is the first description visible to the user in the marketplace.
|
||||
short: String
|
||||
@@ -180,13 +180,13 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
|
||||
ui: Boolean
|
||||
# Denotes the protocol specifications used by this interface
|
||||
protocols: List<String>
|
||||
# Alerts: omitting these will result in using the default alerts in EmbassyOS, except for start, which has no default.
|
||||
# Alerts: omitting these will result in using the default alerts in embassyOS, except for start, which has no default.
|
||||
alerts:
|
||||
install-alert: String
|
||||
uninstall-alert: String
|
||||
restore-alert: String
|
||||
start-alert: String
|
||||
# Specifies how backups should be run for this service. The default EmbassyOS provided option is to use the duplicity backup library on a system image (compat)
|
||||
# Specifies how backups should be run for this service. The default embassyOS provided option is to use the duplicity backup library on a system image (compat)
|
||||
backup:
|
||||
create:
|
||||
type: String
|
||||
@@ -294,6 +294,6 @@ Examples
|
||||
- `Hello World <https://github.com/Start9Labs/hello-world-wrapper/blob/master/manifest.yaml>`__
|
||||
- `Filebrowser <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/manifest.yaml>`__
|
||||
- `Embassy-pages <https://github.com/Start9Labs/embassy-pages-wrapper/blob/master/manifest.toml>`__
|
||||
- `Photoview <https://github.com/Start9Labs/embassyos-photoview-wrapper/blob/master/manifest.yaml>`__
|
||||
- `Photoview <https://github.com/Start9Labs/embassyOS-photoview-wrapper/blob/master/manifest.yaml>`__
|
||||
- `BTCPay Server <https://github.com/Start9Labs/btcpayserver-wrapper/blob/master/manifest.yaml>`__
|
||||
- `Synapse <https://github.com/Start9Labs/synapse-wrapper/blob/master/manifest.yaml>`__
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Package Bundle
|
||||
==============
|
||||
|
||||
All assets get bundled into a custom filetype with an extension of ``.s9pk``, short for Start9 Package. This is the file that will be downloaded from a marketplace. When the user clicks a service's "Install" button, EmbassyOS unpacks and installs the service.
|
||||
All assets get bundled into a custom filetype with an extension of ``.s9pk``, short for Start9 Package. This is the file that will be downloaded from a marketplace. When the user clicks a service's "Install" button, embassyOS unpacks and installs the service.
|
||||
|
||||
The minimum necessary files for this bundle are:
|
||||
|
||||
|
||||
@@ -4,4 +4,4 @@
|
||||
Submission Process
|
||||
==================
|
||||
|
||||
When you have built and tested your project for EmbassyOS, please send Start9 a submission with the project repository to ``dev@start9labs.com``. After being reviewed for security and compatibility, the service will be deployed to the marketplace and available for all EmbassyOS users to download.
|
||||
When you have built and tested your project for embassyOS, please send Start9 a submission with the project repository to ``dev@start9labs.com``. After being reviewed for security and compatibility, the service will be deployed to the marketplace and available for all embassyOS users to download.
|
||||
|
||||
@@ -9,9 +9,9 @@ Each service is bound with a wrapper repository, which contains everything you n
|
||||
The purpose of this repo is:
|
||||
|
||||
- To define the necessary Manifest and configuration options (ie. config spec and rules)
|
||||
- To build the project into the ``.s9pk`` format digestible to EmbassyOS
|
||||
- To build the project into the ``.s9pk`` format digestible to embassyOS
|
||||
- Link to the source project as a git submodule
|
||||
- Define the Dockerfile for running the project on EmbassyOS
|
||||
- Define the Dockerfile for running the project on embassyOS
|
||||
- Provide documentation for the project, especially user runbook instructions
|
||||
|
||||
File Structure
|
||||
|
||||
Reference in New Issue
Block a user