mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
change embassyOS to StartOS & nuance (#357)
* change embassyOS to StartOS & nuance * Update conf.py * Update manifest.rst * say start9 instead of embassy in two links * progress * scrubbed faqs - basic-use, lightning, service-packaging, services, startos * add a few fixes * more * more 'embassy' cleanup * more * the last of embassy (aside from sdk and cli commands, links, etc) * some fixes * update icon, logo, and theme * Update site/source/user-manual/upgrade-hardware/upgrade-pro.rst * Update site/source/developer-docs/packaging.rst * Update site/source/developer-docs/specification/config-spec.rst * Update site/source/learn/concepts/networks.rst * Update site/source/learn/concepts/networks.rst * Update site/source/user-manual/customize.rst * Update site/source/support/faq/faq-basic-use.rst * Update site/source/user-manual/upgrade-hardware/naspi-upgrade.rst * Update site/source/user-manual/upgrade-hardware/upgrade-pro.rst * Update site/source/support/faq/faq-bitcoin.rst * Update site/source/support/faq/faq-bitcoin.rst * Update site/source/support/faq/faq-general.rst * Update site/source/support/faq/faq-general.rst * Update site/source/support/faq/faq-general.rst * Update site/source/support/faq/faq-general.rst * Update site/source/support/faq/faq-services.rst * Update site/source/support/faq/faq-general.rst * Update site/source/support/faq/faq-startos.rst * Update site/source/support/faq/faq-troubleshooting.rst * Update site/source/support/faq/faq-startos.rst * Minor fixes * Fix build errors, ready to roll * Add Beethoven * More fixes * More nother fix * More nother fixes agin * Remove sentence * cards instead --------- Co-authored-by: Matt Hill <matthewonthemoon@gmail.com> Co-authored-by: Shadowy Super Coder <musashidisciple@proton.me> Co-authored-by: Lucy Cifferello <12953208+elvece@users.noreply.github.com> Co-authored-by: kn0wmad <39687477+kn0wmad@users.noreply.github.com> Co-authored-by: agent <kn0wmad@protonmail.com>
This commit is contained in:
BitcoinMechanic
@@ -1,12 +1,12 @@
|
||||
.. _embassy-cli:
|
||||
|
||||
==============================
|
||||
Embassy Command Line Interface
|
||||
StartOS 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 StartOS directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control StartOS 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...
|
||||
|
||||
@@ -14,14 +14,14 @@ In order to use Embassy-CLI, you will first need to authorize yourself with the
|
||||
|
||||
embassy-cli auth login
|
||||
|
||||
and enter your Embassy Master Password at the prompt.
|
||||
and enter your StartOS Master Password at the prompt.
|
||||
|
||||
|
||||
You can enter ``embassy-cli help`` or ``embassy-cli <option> help`` to get an overview of capabilities:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Embassy CLI
|
||||
Embassy-CLI
|
||||
|
||||
USAGE:
|
||||
embassy-cli [OPTIONS] <SUBCOMMAND>
|
||||
@@ -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 StartOS operations and information
|
||||
ssh Manage SSH keys
|
||||
wifi Manage WiFi networks
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
.. _embassy-sdk:
|
||||
|
||||
===========
|
||||
Embassy SDK
|
||||
===========
|
||||
=========
|
||||
Start SDK
|
||||
=========
|
||||
|
||||
The embassyOS embedded Software Development Kit (SDK), is a CLI (Command Line Interface) tool that aids in building and packaging services you wish to deploy to the Embassy.
|
||||
The StartOS embedded Software Development Kit (SDK), is a CLI (Command Line Interface) tool that aids in building and packaging services you wish to deploy to StartOS.
|
||||
|
||||
It helps validate that the necessary components of the package exist, and package all of those components into a special file type (``s9pk``) that is understood by embassyOS.
|
||||
It helps validate that the necessary components of the package exist, and package all of those components into a special file type (``s9pk``) that is understood by StartOS.
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
You can install this component on any system, without needing to run embassyOS, by running the following command:
|
||||
You can install this component on any system, without needing to run StartOS, by running the following command:
|
||||
|
||||
.. code-block::
|
||||
|
||||
git clone -b latest --recursive https://github.com/Start9Labs/embassy-os.git && cd embassy-os/backend && ./install-sdk.sh
|
||||
git clone -b latest --recursive https://github.com/Start9Labs/start-os.git && cd embassy-os/backend && ./install-sdk.sh
|
||||
|
||||
|
||||
Next, initialize the SDK and verify the installation was successful:
|
||||
@@ -63,7 +63,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 StartOS. It expects the following files to exist:
|
||||
|
||||
- Manifest
|
||||
- Instructions
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
.. _embassyd:
|
||||
|
||||
==============
|
||||
Embassy Daemon
|
||||
StartOS 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 StartOS.
|
||||
|
||||
When SSH'd into your Embassy, you may see the status of EmbassyD with the following:
|
||||
When SSH'd into your Start9 server, you may see the status of EmbassyD with the following:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
||||
@@ -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, StartOS 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 StartOS.
|
||||
|
||||
.. 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
|
||||
StartOS developer CLI tools
|
||||
|
||||
.. topic-box::
|
||||
:title: Service Containers
|
||||
@@ -28,7 +28,7 @@ This section included advanced commands for working with packages in embassyOS.
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
How to interact with containers on the Embassy
|
||||
How to interact with containers on the StartOS
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
Developer Docs
|
||||
==============
|
||||
|
||||
Welcome to the Service Packaging documentation for embassyOS. If you are here, you have heard the call to help empower users with sovereign computing!
|
||||
Welcome to the Service Packaging documentation for StartOS. If you are here, you have heard the call to help empower users with sovereign computing!
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Service Packaging
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Welcome! Thank you for your interest in contributing to the growing ecosystem of open software. We call the software applications that run on :ref:`embassyOS<embassy-os>` "services." This distinction is made to differentiate from "applications" (apps), which are generally run on a client, and used to access server-side software (services). To run services on embassyOS, a package of file components needs to be composed. This guide will dive into the basic structure of how to compose this package.
|
||||
Welcome! Thank you for your interest in contributing to the growing ecosystem of open software. We call the software applications that run on :ref:`StartOS<start-os>` "services." This distinction is made to differentiate from "applications" (apps), which are generally run on a client, and used to access server-side software (services). To run services on StartOS, a package of file components needs to be composed. This guide will dive into the basic structure of how to compose this package.
|
||||
|
||||
Check out the :ref:`glossary <glossary>` to get acquainted with unfamiliar terms. The bottom of this guide also includes :ref:`support <packaging-support>` links, including a master checklist.
|
||||
|
||||
@@ -26,7 +26,7 @@ Steps
|
||||
#. :ref:`Create the file structure <create-file-structure>`
|
||||
#. :ref:`Format the package <format-package>`
|
||||
|
||||
#. :ref:`Test the service on embassyOS <testing>`
|
||||
#. :ref:`Test the service on StartOS <testing>`
|
||||
#. :ref:`Submit and/or distribute <submission-and-distribution>`
|
||||
|
||||
.. _choosing-software:
|
||||
@@ -34,9 +34,9 @@ Steps
|
||||
Choosing Software
|
||||
=================
|
||||
|
||||
Almost any type of open source software can be run on embassyOS. No matter what programming language, framework, database or interface the service has, it can be adapted for embassyOS. This is made possible by the power of Docker containers (don't worry, we'll get to this). We do have a few recommendations for choosing a service that will perform optimally across platforms:
|
||||
Almost any type of open source software can be run on StartOS. No matter what programming language, framework, database or interface the service has, it can be adapted for StartOS. This is made possible by the power of Docker containers (don't worry, we'll get to this). We do have a few recommendations for choosing a service that will perform optimally across platforms:
|
||||
|
||||
#. It either has a web user interface (it can be interacted with in a web browser), or is server software that external applications or internal services can connect to. Please keep in mind that embassyOS users are not expected to have SSH and/or CLI access.
|
||||
#. It either has a web user interface (it can be interacted with in a web browser), or is server software that external applications or internal services can connect to. Please keep in mind that StartOS users are not expected to have SSH and/or CLI access.
|
||||
|
||||
- The interfaces supported are: HTTP, TCP, and REST APIs
|
||||
|
||||
@@ -51,7 +51,7 @@ Development Environment
|
||||
|
||||
A basic development and testing environment includes:
|
||||
|
||||
#. An Embassy One or Pro with latest `embassyOS <https://github.com/start9labs/embassy-os/releases>`_
|
||||
#. A Start9 server or VM running the latest `StartOS <https://github.com/Start9Labs/start-os/releases>`_
|
||||
|
||||
- Use your own hardware to `DIY <https://start9.com/latest/diy>`_
|
||||
- Purchase a device from the `Start9 Store <https://store.start9.com>`_
|
||||
@@ -142,7 +142,7 @@ These tools may or may not be necessary, depending on your environment and the p
|
||||
|
||||
Dependencies - Required
|
||||
.......................
|
||||
- `Docker <https://docs.docker.com/get-docker/>`_ - Docker is currently the only supported containerization method for embassyOS. This declares the necessary environment and building stages for your package to run. Install the desktop GUI or via the command line:
|
||||
- `Docker <https://docs.docker.com/get-docker/>`_ - Docker is currently the only supported containerization method for StartOS. This declares the necessary environment and building stages for your package to run. Install the desktop GUI or via the command line:
|
||||
|
||||
.. code-block::
|
||||
|
||||
@@ -163,7 +163,7 @@ Dependencies - Required
|
||||
docker buildx install
|
||||
docker buildx create --use
|
||||
|
||||
- Rust & Cargo - Cargo is the package management solution for the Rust programming language. It is needed to build the Embassy SDK. The following will install both Rust and Cargo:
|
||||
- Rust & Cargo - Cargo is the package management solution for the Rust programming language. It is needed to build the Start SDK. The following will install both Rust and Cargo:
|
||||
|
||||
.. code-block::
|
||||
|
||||
@@ -176,11 +176,11 @@ Dependencies - Required
|
||||
|
||||
cargo --version
|
||||
|
||||
- Embassy SDK - embassyOS has an embedded Software Development Kit (SDK). You can install this component on any system, without needing to run embassyOS.
|
||||
- Start SDK - StartOS has an embedded Software Development Kit (SDK). You can install this component on any system, without needing to run StartOS.
|
||||
|
||||
.. code-block::
|
||||
|
||||
git clone -b latest --recursive https://github.com/Start9Labs/embassy-os.git && cd embassy-os/backend && ./install-sdk.sh
|
||||
git clone -b latest --recursive https://github.com/Start9Labs/start-os.git && cd start-os/backend && ./install-sdk.sh
|
||||
|
||||
Initialize sdk & verify install
|
||||
|
||||
@@ -207,7 +207,7 @@ Dependencies - Required
|
||||
|
||||
Demo with Hello World
|
||||
=====================
|
||||
Check your environment setup by building a demo project and installing it to embassyOS.
|
||||
Check your environment setup by building a demo project and installing it to StartOS.
|
||||
|
||||
#. Get Hello World
|
||||
|
||||
@@ -225,7 +225,7 @@ Check your environment setup by building a demo project and installing it to emb
|
||||
make
|
||||
|
||||
#. Sideload & Run
|
||||
- In the embassyOS web UI menu, navigate to `Embassy -> Settings -> Sideload Service`
|
||||
- In the StartOS web UI menu, navigate to `System -> Sideload Service`
|
||||
- Drag and drop or select the ``hello-world.s9pk`` from your filesystem to install
|
||||
- Once the service has installed, navigate to `Services -> Hello World` and click "Start"
|
||||
- Once the Health Check is successful, click "Launch UI" and verify you see the Hello World page
|
||||
@@ -234,13 +234,13 @@ Check your environment setup by building a demo project and installing it to emb
|
||||
|
||||
Package the service
|
||||
===================
|
||||
The package file produced by this process has a ``s9pk`` extension. This file is what is installed to run a service on embassyOS.
|
||||
The package file produced by this process has a ``s9pk`` extension. This file is what is installed to run a service on StartOS.
|
||||
|
||||
.. _build-a-dockerfile:
|
||||
|
||||
Build a Dockerfile
|
||||
..................
|
||||
A Dockerfile defines the recipe for building the environment to run a service. Currently, embassyOS only supports one Dockerfile per project (i.e. no Docker compose), so it should include any necessary database configurations. There are several methods to build a Dockerfile for your service.
|
||||
A Dockerfile defines the recipe for building the environment to run a service. Currently, StartOS only supports one Dockerfile per project (i.e. no Docker compose), so it should include any necessary database configurations. There are several methods to build a Dockerfile for your service.
|
||||
|
||||
First, check to see if the upstream project has already built one. This is usually your best source for finding Docker images that are compatible with ARM. Next, you can:
|
||||
|
||||
@@ -363,13 +363,13 @@ Testing
|
||||
|
||||
#. Drag and drop:
|
||||
|
||||
- In the embassyOS web UI menu, navigate to `Embassy -> Settings -> Sideload Service`
|
||||
- In the StartOS web UI menu, navigate to `System -> Sideload Service`
|
||||
|
||||
- Drag and drop or select the ``<package>.s9pk`` from your filesystem to install
|
||||
|
||||
#. Use the CLI:
|
||||
|
||||
- Create a config file with the IP address of the device running embassyOS:
|
||||
- Create a config file with the IP address of the device running StartOS:
|
||||
|
||||
.. code-block::
|
||||
|
||||
@@ -410,8 +410,8 @@ The ``s9pk`` file can be uploaded for distribution to any website, repository, o
|
||||
Advanced configuration
|
||||
======================
|
||||
|
||||
Scripting on embassyOS
|
||||
......................
|
||||
Scripting on StartOS
|
||||
....................
|
||||
|
||||
Start9 has developed a highly extensible scripting API for developers to create the best possible user experience. This is your toolkit for creating the most powerful service possible by enabling features such as:
|
||||
|
||||
@@ -440,7 +440,7 @@ You may like to use this handy :ref:`Checklist <packaging-checklist>` to be sure
|
||||
Glossary
|
||||
========
|
||||
|
||||
`service` - open software applications that run on embassyOS
|
||||
`service` - open software applications that run on StartOS
|
||||
|
||||
`package` - the composed set of a Docker image, a service manifest, and service instructions, icon, and license, that are formatted into a file with the `s9pk` extension using `embassy-sdk`
|
||||
|
||||
@@ -448,17 +448,17 @@ Glossary
|
||||
|
||||
`scripts` - a set of developer APIs that enable advanced configuration options for services
|
||||
|
||||
`embassy-sdk` - the Software Development Toolkit used to package and verify services for embassyOS
|
||||
`embassy-sdk` - the Software Development Toolkit used to package and verify services for StartOS
|
||||
|
||||
`open source software` - computer software that is released under a license in which the copyright holder grants users the rights to use, study, change, and distribute the software and its source code to anyone and for any purpose
|
||||
|
||||
`upstream project` - the original, source project code that is used as the base for a service
|
||||
|
||||
`embassyOS` - a browser-based, graphical operating system for a personal server
|
||||
`StartOS` - a browser-based, graphical operating system for a personal server
|
||||
|
||||
`eOS` - shorthand for embassyOS
|
||||
`eOS` - shorthand for StartOS
|
||||
|
||||
`s9pk` - the file extension for the packaged service artifact needed to install and run a service on embassyOS
|
||||
`s9pk` - the file extension for the packaged service artifact needed to install and run a service on StartOS
|
||||
|
||||
|
||||
:ref:`Back to Top <service-packaging>`
|
||||
|
||||
@@ -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_.
|
||||
StartOS 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:
|
||||
|
||||
|
||||
@@ -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 <service-packaging>` guide.
|
||||
This guide outlines a checklist of steps to complete in order to package a service for StartOS. For a more in depth example, visit the :ref:`build your first package <service-packaging>` guide.
|
||||
|
||||
Packaging
|
||||
---------
|
||||
@@ -30,7 +30,7 @@ Packaging
|
||||
Testing:
|
||||
--------
|
||||
|
||||
1. Sideload ``<package-id>.s9pk`` onto an Embassy
|
||||
1. Sideload ``<package-id>.s9pk`` onto StartOS
|
||||
2. Install package using embassy-cli
|
||||
3. Start package using embassy-cli, or in the UI
|
||||
4. Check logs to see if errors
|
||||
|
||||
@@ -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 StartOS 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 StartOS 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 StartOS 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 StartOS, 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 StartOS 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 StartOS (ie. package subtype) or to the StartOS 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 StartOS, 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.
|
||||
|
||||
@@ -438,7 +438,7 @@ Example
|
||||
id: type
|
||||
name: Type
|
||||
description: |
|
||||
- Internal: The Bitcoin Core service installed to your Embassy
|
||||
- Internal: The Bitcoin Core service installed on your server
|
||||
- External: A Bitcoin Core node running on a different device
|
||||
- Quick Connect: A Quick Connect URL for an unpruned Bitcoin Core node
|
||||
variant-names:
|
||||
|
||||
@@ -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 StartOS 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. StartOS 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 StartOS, 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 StartOS (such as Bitcoin), sometimes even a particular version of those services. These need to be specified by the developers so that StartOS 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 StartOS 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 StartOS 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 StartOS, 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 StartOS, services can declare as one or many volumes in the Manifest:
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
|
||||
@@ -6,25 +6,25 @@ 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 StartOS:
|
||||
|
||||
.. figure:: /_static/images/services/service-instruct.png
|
||||
:width: 80%
|
||||
:alt: Embassy Pages Instructions
|
||||
:alt: Start9 Pages Instructions
|
||||
|
||||
Below is the markdown file for Embassy Pages' instructions, as shown above:
|
||||
Below is the markdown file for Start9 Pages' instructions, as shown above:
|
||||
|
||||
.. code-block::
|
||||
|
||||
# Embassy Pages
|
||||
# Start9 Pages
|
||||
|
||||
## About
|
||||
|
||||
Embassy Pages is a simple web server that uses directories inside File Browser to serve Tor websites. Your website could be a blog, a resume, a portfolio, a business landing page, a product brochure, or just a set of static folders and/or files that you want to share with the world.
|
||||
Start9 Pages is a simple web server that uses directories inside File Browser to serve Tor websites. Your website could be a blog, a resume, a portfolio, a business landing page, a product brochure, or just a set of static folders and/or files that you want to share with the world.
|
||||
|
||||
When you first install Embassy Pages, there will be a default Homepage hosted at the root, <tor-address>.onion. You can change the behavior of this page, and you can also create Subdomain websites. For example, one site could be hello.<tor-address>.onion and another could be goodbye.<tor-address>.onion. What is served from the Homepage and each Subdomain is totally up to you.
|
||||
When you first install Start9 Pages, there will be a default Homepage hosted at the root, <tor-address>.onion. You can change the behavior of this page, and you can also create Subdomain websites. For example, one site could be hello.<tor-address>.onion and another could be goodbye.<tor-address>.onion. What is served from the Homepage and each Subdomain is totally up to you.
|
||||
|
||||
Self-hosting Tor websites using Embassy Pages is easy, permissionless, and censorship-resistant; there are no trusted third parties involved.
|
||||
Self-hosting Tor websites using Start9 Pages is easy, permissionless, and censorship-resistant; there are no trusted third parties involved.
|
||||
Anyone can do it. No one can stop it.
|
||||
|
||||
## Instructions
|
||||
@@ -37,18 +37,18 @@ Below is the markdown file for Embassy Pages' instructions, as shown above:
|
||||
|
||||
2. Inside `Config`, you can create one or more Subdomains, giving each a unique name.
|
||||
|
||||
3. To serve a personal website, simply upload the website directory to File Browser. Then, inside the settings for a particular page (either your Homepage or a Subdomain), enter the path to that directory. For example, a path of websites/blog would tell Embassy Pages that it can find the blog website inside the websites directory in File Browser.
|
||||
3. To serve a personal website, simply upload the website directory to File Browser. Then, inside the settings for a particular page (either your Homepage or a Subdomain), enter the path to that directory. For example, a path of websites/blog would tell Start9 Pages that it can find the blog website inside the websites directory in File Browser.
|
||||
|
||||
4. A list of all your Subdomains can be found inside the Properties section of your Embassy Pages service.
|
||||
4. A list of all your Subdomains can be found inside the Properties section of your Start9 Pages service.
|
||||
|
||||
## Restore from Backup
|
||||
|
||||
1. In `Config`, select "Restore from Backup".
|
||||
2. After the restoration completes, navigate to the Marketplace.
|
||||
3. Downgrade Embassy Pages.
|
||||
4. Upgrade Embassy Pages to the latest version.
|
||||
5. Start Embassy Pages.
|
||||
6. Embassy Pages is now successfully restored!
|
||||
3. Downgrade Start9 Pages.
|
||||
4. Upgrade Start9 Pages to the latest version.
|
||||
5. Start Start9 Pages.
|
||||
6. Start9 Pages is now successfully restored!
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
@@ -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/types.ts>`__.
|
||||
**Effects**: A TypeScript object that is used to interact with StartOS. See the `full definition here <https://deno.land/x/embassyd_sdk/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.3.0.5/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.3.0.5/types.ts#L32>`_. This type describes how to call functions that interact with StartOS.
|
||||
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 StartOS - 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:`StartOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. StartOS 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 StartOS - 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 StartOS
|
||||
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 StartOS 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 StartOS, 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 StartOS provided option is to use the duplicity backup library on a system image (compat)
|
||||
backup:
|
||||
create:
|
||||
type: String
|
||||
@@ -293,7 +293,7 @@ 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>`__
|
||||
- `Start9-pages <https://github.com/Start9Labs/start9-pages-wrapper/blob/master/manifest.toml>`__
|
||||
- `Photoview <https://github.com/Start9Labs/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, StartOS unpacks and installs the service.
|
||||
|
||||
The minimum necessary files for this bundle are:
|
||||
|
||||
|
||||
@@ -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 StartOS
|
||||
- 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 StartOS
|
||||
- Provide documentation for the project, especially user runbook instructions
|
||||
|
||||
File Structure
|
||||
|
||||
Reference in New Issue
Block a user