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 @@ Embassy Command Line Interface
|
||||
|
||||
.. warning:: This is for advanced users only!! Anything you do while SSH'd into your Embassy is NOT SUPPORTED, unless under the guidance of a Start9 technician.
|
||||
|
||||
When interacting with Embassy directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control EmbassyOS in many of the same ways that the UI can, but with finer controls and deeper insights.
|
||||
When interacting with Embassy directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control embassyOS in many of the same ways that the UI can, but with finer controls and deeper insights.
|
||||
|
||||
In order to use Embassy-CLI, you will first need to authorize yourself with the following command...
|
||||
|
||||
@@ -47,6 +47,6 @@ You can enter ``embassy-cli help`` or ``embassy-cli <option> help`` to get an ov
|
||||
net Network information
|
||||
notification Control UI notifications
|
||||
package Interact with packages
|
||||
server EmbassyOS operations and information
|
||||
server embassyOS operations and information
|
||||
ssh Manage SSH keys
|
||||
wifi Manage WiFi networks
|
||||
|
||||
@@ -40,4 +40,4 @@ You can enter ``embassy-sdk help`` or ``embassy-sdk <option> help`` to get an ov
|
||||
verify Verify a .s9pk is valid
|
||||
|
||||
|
||||
Please visit the `EmbassyOS backend <https://github.com/Start9Labs/embassy-os/tree/master/backend>`_ for more details
|
||||
Please visit the `embassyOS backend <https://github.com/Start9Labs/embassy-os/tree/master/backend>`_ for more details
|
||||
|
||||
@@ -6,7 +6,7 @@ Embassy Daemon
|
||||
|
||||
.. warning:: This is for advanced users only!! Anything you do while SSH'd into your Embassy is NOT SUPPORTED, unless under the guidance of a Start9 technician.
|
||||
|
||||
``embassyd`` is the daemon that runs everything that could be considered EmbassyOS.
|
||||
``embassyd`` is the daemon that runs everything that could be considered embassyOS.
|
||||
|
||||
When SSH'd into your Embassy, you may see the status of EmbassyD with the following:
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Service Containers
|
||||
==================
|
||||
|
||||
For simplicity, EmbassyOS is designed to be completely operated via the :ref:`WebUI <web-ui>`, however, your device belongs to you and if you want to "lift the hood" and access the internals of the software, you may do so. This guide will show you how to enter a Service's Docker container in order to directly interface with it and issue commands.
|
||||
For simplicity, embassyOS is designed to be completely operated via the :ref:`WebUI <web-ui>`, however, your device belongs to you and if you want to "lift the hood" and access the internals of the software, you may do so. This guide will show you how to enter a Service's Docker container in order to directly interface with it and issue commands.
|
||||
|
||||
.. warning:: The following guide is for those that have advanced command line skills, or those who are being guided by a Start9 support technician. Nothing you do inside a container is supported unless under the direction of Start9. Here be dragons!!
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Advanced
|
||||
========
|
||||
|
||||
This section included advanced commands for working with packages in EmbassyOS.
|
||||
This section included advanced commands for working with packages in embassyOS.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -19,7 +19,7 @@ This section included advanced commands for working with packages in EmbassyOS.
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
EmbassyOS developer CLI tools
|
||||
embassyOS developer CLI tools
|
||||
|
||||
.. topic-box::
|
||||
:title: Service Containers
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
3 - Hardware Build
|
||||
==================
|
||||
|
||||
EmbassyOS is run on the arm-v8 architecture, specifically the aarch64 state, for the RaspberryPi.
|
||||
embassyOS is run on the arm-v8 architecture, specifically the aarch64 state, for the RaspberryPi.
|
||||
|
||||
Depending on the programming language or libraries used in a project, you might need to set up an environment to *cross compile* the executable for this runtime environment.
|
||||
|
||||
|
||||
@@ -61,7 +61,7 @@ In other words, the Dockerfile serves as a recipe for creating a Docker image, f
|
||||
|
||||
WORKDIR /root
|
||||
|
||||
# not necessary for EmbassyOS, but often left for quick reference and clarity
|
||||
# not necessary for embassyOS, but often left for quick reference and clarity
|
||||
EXPOSE 80
|
||||
|
||||
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
5 - Create Manifest
|
||||
===================
|
||||
|
||||
The Manifest file specifies the details EmbassyOS needs to operate a service. It is the connection point between your service and EmbassyOS.
|
||||
The Manifest file specifies the details embassyOS needs to operate a service. It is the connection point between your service and embassyOS.
|
||||
|
||||
In this file, values and actions exist for:
|
||||
|
||||
@@ -36,10 +36,10 @@ And populate it with the following example manifest (see the line comments for a
|
||||
id: hello-world
|
||||
# A human readable service title
|
||||
title: "Hello World"
|
||||
# Service version - accepts up to four digits, where the last confirms to revisions necessary for EmbassyOS - see documentation: https://github.com/Start9Labs/emver-rs
|
||||
# Service version - accepts up to four digits, where the last confirms to revisions necessary for embassyOS - see documentation: https://github.com/Start9Labs/emver-rs
|
||||
version: 0.3.0
|
||||
# Release notes for the update - can be a string, paragraph or URL
|
||||
release-notes: "Upgrade to EmbassyOS v0.3.0"
|
||||
release-notes: "Upgrade to embassyOS v0.3.0"
|
||||
# The type of license for the project. Include the LICENSE in the root of the project directory. A license is required for a Start9 package.
|
||||
license: mit
|
||||
# The Start9 wrapper repository URL for the package. This repo contains the manifest file (this), any scripts necessary for configuration, backups, actions, or health checks (more below). This key must exist. But could be embedded into the source repository.
|
||||
@@ -52,9 +52,9 @@ And populate it with the following example manifest (see the line comments for a
|
||||
marketing-site: "https://start9.com/"
|
||||
# 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: ["make"]
|
||||
# Minimum required version of EmbassyOS
|
||||
# Minimum required version of embassyOS
|
||||
min-os-version: "0.3.0"
|
||||
# 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: Example service
|
||||
@@ -190,13 +190,13 @@ And populate it with the following example manifest (see the line comments for a
|
||||
protocols:
|
||||
- tcp
|
||||
- http
|
||||
# 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: This is an alert that will present before the user installs this service
|
||||
uninstall-alert: This is an alert that will present before the user uninstalls this service
|
||||
restore-alert: This is an alert that will present before the user restores this service from Embassy backup
|
||||
start-alert: This is an alert that will present before the user starts this service
|
||||
# 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:
|
||||
# Currently, only docker actions are supported.
|
||||
|
||||
@@ -36,7 +36,7 @@ And add the following code to the file:
|
||||
License
|
||||
-------
|
||||
|
||||
Start9 ensures that the proper license is displayed for all open source software running on an EmbassyOS platform. Let's make sure to include the full open source license so users can view the distribution permissions of your service, among other licensing details.
|
||||
Start9 ensures that the proper license is displayed for all open source software running on an embassyOS platform. Let's make sure to include the full open source license so users can view the distribution permissions of your service, among other licensing details.
|
||||
|
||||
The name and location of this file should be specified in the ``assets.license`` section of the Manifest. The default value if not specified is ``LICENSE``, located in the root of the project folder.
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
10 - Install
|
||||
============
|
||||
|
||||
Now that we have a process for iterating on producing a valid package for EmbassyOS, let's load it onto an Embassy!
|
||||
Now that we have a process for iterating on producing a valid package for embassyOS, let's load it onto an Embassy!
|
||||
|
||||
1. First, generate an ssh key for the Embassy:
|
||||
|
||||
@@ -46,7 +46,7 @@ Now that we have a process for iterating on producing a valid package for Embass
|
||||
embassy-cli auth login
|
||||
embassy-cli package install hello-world.s9pk
|
||||
|
||||
**Congratulations!** You have successfully created and installed a package you created onto EmbassyOS. The package should now be viewable in the "Services" tab in EmbassyUI.
|
||||
**Congratulations!** You have successfully created and installed a package you created onto embassyOS. The package should now be viewable in the "Services" tab in EmbassyUI.
|
||||
|
||||
From here, you can play with viewing the results of your Manifest file settings, such as config, actions, interfaces, health checks, etc. You can also view the logs of your service right in the UI!
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Build a Package
|
||||
===============
|
||||
|
||||
This guide will take you through the fundamentals of packaging a service for EmbassyOS by creating a real service. Let's get started!
|
||||
This guide will take you through the fundamentals of packaging a service for embassyOS by creating a real service. Let's get started!
|
||||
|
||||
.. raw:: html
|
||||
|
||||
@@ -90,7 +90,7 @@ This guide will take you through the fundamentals of packaging a service for Emb
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Install packaged service on EmbassyOS
|
||||
Install packaged service on embassyOS
|
||||
|
||||
.. topic-box::
|
||||
:title: Resources
|
||||
|
||||
@@ -16,7 +16,7 @@ If you get stuck or are having issues debugging why your service is not packagin
|
||||
Submission Process
|
||||
------------------
|
||||
|
||||
When you have built and tested your project for EmbassyOS, please send Start9 a submission to dev@start9labs.com with a link to the wrapper repository. After being reviewed for security and compatibility, the service will be deployed to the Start9 Marketplace and available for all EmbassyOS users to download.
|
||||
When you have built and tested your project for embassyOS, please send Start9 a submission to dev@start9labs.com with a link to the wrapper repository. After being reviewed for security and compatibility, the service will be deployed to the Start9 Marketplace and available for all embassyOS users to download.
|
||||
|
||||
If you are deploying to an alternative marketplace, please shout it out in our community channels!
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Checklist
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
This guide outlines a checklist of steps to complete in order to package a service for EmbassyOS. For a more in depth example, visit the :ref:`build your first package <build-package-example>` guide.
|
||||
This guide outlines a checklist of steps to complete in order to package a service for embassyOS. For a more in depth example, visit the :ref:`build your first package <build-package-example>` guide.
|
||||
|
||||
Packaging
|
||||
---------
|
||||
|
||||
@@ -8,7 +8,7 @@ Environment Setup
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
To get started packaging a service for EmbassyOS, some basic knowledge of software development is required. Don't worry if you are inexperienced, we will provide enough context to get you started, and you can always reach out with questions.
|
||||
To get started packaging a service for embassyOS, some basic knowledge of software development is required. Don't worry if you are inexperienced, we will provide enough context to get you started, and you can always reach out with questions.
|
||||
|
||||
If you are already an experienced developer, :ref:`jump ahead <environment-quick-start>`.
|
||||
|
||||
@@ -46,7 +46,7 @@ To verify the installation, open a new terminal window and run:
|
||||
Docker
|
||||
------
|
||||
|
||||
`Docker <https://docs.docker.com/get-docker>`_ must be installed on your computer. It is needed to build an image for your package, which will be used to create the running instance of your package on EmbassyOS. In essence, it declares the necessary environment and building stages for your package to run.
|
||||
`Docker <https://docs.docker.com/get-docker>`_ must be installed on your computer. It is needed to build an image for your package, which will be used to create the running instance of your package on embassyOS. In essence, it declares the necessary environment and building stages for your package to run.
|
||||
|
||||
We also recommend installing and using `Docker buildx <https://docs.docker.com/buildx/working-with-buildx/>`_, as this adds desirable new features to the Docker build experience. It is included by default with Docker Desktop for Windows and macOS.
|
||||
|
||||
@@ -54,7 +54,7 @@ We also recommend installing and using `Docker buildx <https://docs.docker.com/b
|
||||
Cargo
|
||||
-----
|
||||
|
||||
Cargo is the package management solution for the Rust programming language. It will install Rust to your system, and provide the required environment to build the Embassy SDK for packaging your service into the required format needed by EmbassyOS.
|
||||
Cargo is the package management solution for the Rust programming language. It will install Rust to your system, and provide the required environment to build the Embassy SDK for packaging your service into the required format needed by embassyOS.
|
||||
|
||||
Installation instructions for Cargo can be found `here <https://doc.rust-lang.org/cargo/getting-started/installation.html>`__.
|
||||
|
||||
@@ -67,7 +67,7 @@ To verify the installation, open a terminal window and run:
|
||||
SDK
|
||||
---
|
||||
|
||||
EmbassyOS provides a :ref:`software development kit <sdk>` embedded in its environment. You do not need a running instance of EmbassyOS to use this component, it can be installed on any computer platform.
|
||||
embassyOS provides a :ref:`software development kit <sdk>` embedded in its environment. You do not need a running instance of embassyOS to use this component, it can be installed on any computer platform.
|
||||
|
||||
To install the SDK:
|
||||
|
||||
@@ -81,10 +81,10 @@ To verify the installation, open a terminal window and run:
|
||||
|
||||
embassy-sdk --version
|
||||
|
||||
EmbassyOS
|
||||
embassyOS
|
||||
---------
|
||||
|
||||
While not strictly necessary, having a running instance of EmbassyOS is recommended to test installing, running, configuring, and using your package. Without this component, you will have to coordinate with Start9's internal development team to test.
|
||||
While not strictly necessary, having a running instance of embassyOS is recommended to test installing, running, configuring, and using your package. Without this component, you will have to coordinate with Start9's internal development team to test.
|
||||
|
||||
.. _environment-quick-start:
|
||||
|
||||
@@ -93,5 +93,5 @@ Quick Start Environment Setup
|
||||
- `Docker <https://docs.docker.com/get-docker>`_
|
||||
- `Docker buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
|
||||
- `Cargo <https://doc.rust-lang.org/cargo/getting-started/installation.html>`__
|
||||
- `EmbassyOS <https://github.com/Start9Labs/embassy-os>`_
|
||||
- `embassyOS <https://github.com/Start9Labs/embassy-os>`_
|
||||
- `Embassy SDK <https://github.com/Start9Labs/embassy-os/blob/master/backend/install-sdk.sh>`_
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
Select an option below to get started with packing a service for EmbassyOS.
|
||||
Select an option below to get started with packing a service for embassyOS.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ Embassy SDK
|
||||
|
||||
Embassy SDK, or Software Development Kit, is a CLI (Command Line Interface) tool that aids in building and packaging services you wish to deploy to the Embassy.
|
||||
|
||||
It mainly helps you validate that the necessary components of your package exist, and package all of those components into a special file type that is understood by EmbassyOS.
|
||||
It mainly helps you validate that the necessary components of your package exist, and package all of those components into a special file type that is understood by embassyOS.
|
||||
|
||||
To install, checkout the SDK step in :ref:`setting up your environment <environment-setup>`.
|
||||
|
||||
@@ -47,7 +47,7 @@ And load it by running:
|
||||
embassy-sdk pack
|
||||
----------------
|
||||
|
||||
This command takes the necessary package components and assembles them into the `s9pk` file format needed to install a service on EmbassyOS. It expects the following files to exist:
|
||||
This command takes the necessary package components and assembles them into the `s9pk` file format needed to install a service on embassyOS. It expects the following files to exist:
|
||||
|
||||
- Manifest
|
||||
- Instructions
|
||||
|
||||
@@ -4,13 +4,13 @@
|
||||
Developer Docs
|
||||
==============
|
||||
|
||||
Welcome to Service Packaging for EmbassyOS!
|
||||
Welcome to Service Packaging for embassyOS!
|
||||
|
||||
If you are here, you are interested in becoming part of the mission to change the future of personal computing.
|
||||
|
||||
The guides below provide the fundamentals that will take you through the process of packing a service for EmbassyOS. Services are any open source project (application) that can be run on a self-hosted platform, independent of third parties.
|
||||
The guides below provide the fundamentals that will take you through the process of packing a service for embassyOS. Services are any open source project (application) that can be run on a self-hosted platform, independent of third parties.
|
||||
|
||||
By configuring and packaging a project according to these guides, it can be installed on EmbassyOS so that users can interact with the service without needing any technical expertise.
|
||||
By configuring and packaging a project according to these guides, it can be installed on embassyOS so that users can interact with the service without needing any technical expertise.
|
||||
|
||||
Let's get started!
|
||||
|
||||
|
||||
@@ -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