remove build artifacts

This commit is contained in:
Lucy Cifferello
2021-12-16 11:34:14 -07:00
parent 584a4cda5e
commit a61c79d6b3
510 changed files with 4 additions and 60094 deletions

2
.gitignore vendored
View File

@@ -3,3 +3,5 @@
build/
build-send.sh
utils/deploy.sh
docs/_build
.env

View File

@@ -1,4 +0,0 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 08addde01d713beb7fdd9a5fa8fa3bb9
tags: d77d1c0d9ca2f4c8421862c7c5a0d620

View File

@@ -1,36 +0,0 @@
<!DOCTYPE html>
<html class="no-js height" lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>Start9</title>
<meta name="description" content="Start9 Product Documentation and Education Guides" />
<link rel="icon" src="/_static/img/favicon.ico" type="image/x-icon" />
<link rel="preconnect" href="https://fonts.gstatic.com" />
<link
href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap"
rel="stylesheet"
/>
<link rel="stylesheet" href="/_static/css/main.css" type="text/css" />
<link
rel="stylesheet"
href="/en/latest/_static/css/main.css"
type="text/css"
/>
</head>
<body class="not-found">
<img class="not-found__icon" src="/_static/img/404.jpg" alt="" />
<div class="not-found__text">
<h1>404</h1>
<p>We cannot find what you are looking for!</p>
<p>
<a href="https://docs.start9.com" class="button not-found__button">Home</a>
</p>
</div>
</body>
</html>

View File

@@ -1,36 +0,0 @@
<!DOCTYPE html>
<html class="no-js height" lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<title>Start9</title>
<meta name="description" content="Start9 Product Documentation and Education Guides" />
<link rel="icon" src="/_static/img/favicon.ico" type="image/x-icon" />
<link rel="preconnect" href="https://fonts.gstatic.com" />
<link
href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap"
rel="stylesheet"
/>
<link rel="stylesheet" href="/_static/css/main.css" type="text/css" />
<link
rel="stylesheet"
href="/en/latest/_static/css/main.css"
type="text/css"
/>
</head>
<body class="not-found">
<img class="not-found__icon" src="/_static/img/404.jpg" alt="" />
<div class="not-found__text">
<h1>404</h1>
<p>We cannot find what you are looking for!</p>
<p>
<a href="https://docs.start9.com" class="button not-found__button">Home</a>
</p>
</div>
</body>
</html>

Binary file not shown.

Before

Width:  |  Height:  |  Size: 319 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 126 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 130 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 131 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 132 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 11 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 988 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 494 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 41 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 514 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 504 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 272 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 500 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 534 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 346 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 591 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 295 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 255 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 180 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 176 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 478 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 323 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 294 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 288 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 351 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 478 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 304 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 62 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 111 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 39 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 150 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 92 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 56 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 411 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 567 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 23 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 63 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 239 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 1.1 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 273 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 135 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 499 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 504 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 502 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 336 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 492 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 389 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 488 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 472 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 557 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 532 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 481 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 464 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 75 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 81 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 59 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 106 KiB

View File

@@ -1,14 +0,0 @@
.. _embassyos_contribute:
*********
EmbassyOS
*********
We ❤️ contributions!
Please follow the guide `here <https://github.com/Start9Labs/embassy-os/blob/master/CONTRIBUTING.md>`_ and reach out to the `community dev <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ channel on Matrix with any questions.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,29 +0,0 @@
.. _service_backups:
***************
Service Backups
***************
Everything within the root of the mounted volume directory will be stored in an EmbassyOS backup. This includes the config (config.yaml) and properties (stats.yaml) files, as well as any other persisted data within the volume directory.
For restoration purposes, it might be beneficial to ignore certain files or folders. For instance, ignore the shared/public folder that is mounted for dependencies that expose this feature as it causes data inconsistencies on restore.
In this case, create a `.backupignore` file. This file contains a list of relative paths to the ignored files.
Example
=======
The `btcpayserver wrapper <https://github.com/Start9Labs/btcpayserver-wrapper/blob/master/configurator/src/templates/.backupignore.templates>`_ demonstrates a good use of a backupignore template.
Ultimately, ``/datadir/.backupignore`` gets populated with:
.. code::
/root/volumes/btcpayserver/start9/public
/root/volumes/btcpayserver/start9/shared
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,617 +0,0 @@
.. _service_config:
****************************
Service Config Specification
****************************
Overview
========
Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's configuration will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and dependency management.
The outcome of this step is two files:
:ref:`config_spec.yaml <config_spec>`
:ref:`config_rules.yaml <config_rules>`
These files contain a detailed mapping of configuration options with acceptable values, defaults, and relational rule-sets.
For example, if the user chooses config option A, then config option B must be between 5 and 10. This enables a simple GUI configuration experience, complete with validations and protections, for users. They do not have to worry about the consequences of a wrong value in a ``.conf`` file.
.. _config_spec:
Config Spec
===========
Overview
--------
.. figure:: /_static/images/service/bitcoin_config.png
:width: 80%
:alt: Bitcoin Config
This file defines the structure of configuration options your service depends on to run. It additionally can include configuration options that users might want to enable for more advanced or customized usage. Ultimately, these values influence the UI elements for a user to interact with. Specifically, they evaluate to the options available when managing a service, such as:
- Prior to service installation when the user needs to be made aware of any necessary dependency configurations
- When the user installs a service and the service is in the "Needs Config" state
- Whenever a user edits a service config
- When config pointers get updated
The neat part about this file is that each ValueSpec type gets translated into a specific front end component. For instance, boolean values display as a toggle button.
.. figure:: /_static/images/service/boolean_toggle.png
:width: 80%
:alt: Example boolean toggle
Another advantage is the ability to define default values. These values automatically get populated if the user selects the ``Default`` option when setting up a service in ``Needs Config`` state. This is super convenient for users who want to get up and running quickly.
Types
-----
ConfigSpec Type:
.. code::
key: ValueSpec
ValueSpec Type: Boolean | Enum | List | Number | Object | String | Union | Pointer (see below for details)
Implementation Guide
--------------------
The following section contains implementation specifications for the ``config_spec.yaml`` file.
- All keys are ``kebab-case`` strings, which correspond to the service (app) id
- All values are one the following specs (ie. ``ValueSpec`` type):
:ref:`boolean <boolean>`
:ref:`enum <enum>`
:ref:`list <list>`
:ref:`number <number>`
:ref:`object <object>`
:ref:`string <string>`
:ref:`union <union>`
:ref:`pointer <pointer>`
- In the examples for each value spec type below, ``Option`` means the key is optional. Otherwise, the key is required.
- Descriptions are optional, but recommended
- Name corresponds to the name of the config field
- Find a complete example :ref:`here <example_config_spec>`
- Change warning text displays when the value is altered
.. _boolean:
Boolean
^^^^^^^
Config value specification denoted as a boolean value. A default value is required.
``ValueSpec`` Type:
.. code::
type: boolean
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
Example:
.. code:: yaml
fetch-blocks:
type: boolean
name: Fetch Blocks
description: Fetch blocks from the network if pruned from disk
default: true
.. _enum:
Enum
^^^^
Config value specification denoted as an enum value. Enums values must be a unique set. If no default is provided, ``null`` will be the assumed value.
ValueSpec Type:
.. code::
type: enum
name: String
description: Option<String>
changeWarning: Option<String>
default: Option<Enum>
values: Set<String>
.. code:: yaml
theme-mode:
type: enum
name: Theme Mode
values:
- NIGHT
- DAY
valueNames:
NIGHT: Night
DAY: Day
default: NIGHT
.. _list:
List
^^^^
The list type describes an array of values. The values must consist of the same subtype, which can be any of the ValueSpec types available in the EmbassyOS config specification.
Lists of any type do not contain the default for each item in list. The list *itself* can have a default. If no default is provided, ``null`` will be the assumed value.
Range is loosely based off mathematical range syntax, with infinity replaced with ``*``:
``[ || ]`` = inclusive
``( || )`` = noninclusive
``*`` = infinity on either end
eg:
.. code::
[0,*) - all numbers to infinity including 0
ValueSpec Type:
.. code::
type: list
name: String
description: Option<String>
subtype: enum || number || object || string || union
range: NumRange<unsigned integer>
spec: ValueSpec
default: ValueSpec
Example:
.. code:: yaml
allowed-calls:
type: list
name: Allowed Calls
description: The list of all RPC methods this user is allowed to make
subtype: enum
range: "[0, *)"
spec:
type: enum
values:
- item
- item
.. _number:
Number
^^^^^^
A number value within an optionally defined range. Nullable field is required. If ``nullable`` is true, the default is assumed to be ``null`` if it is not provided.
ValueSpec Type:
.. code::
type: number
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
nullable: Boolean
range: Option<NumRange<64 bit floating point>>
integral: Boolean
units: Option<String>
Example:
.. code:: yaml
type: number
name: Peer Message Timeout
description: How long to wait for a response from a peer before failing
nullable: false
integral: true
units: Seconds
range: "[0, *)"
default: 30
.. _object:
Object Type
^^^^^^^^^^^
A nested representation of a ConfigSpec. The object type takes the same structure under the ``spec`` key as a ConfigSpec: a key indicates the field name, and the value denotes the ValueSpec type for that field.
There is no default option for the object type. Rather, the option ``null-by-default`` should be used to indicate the default as ``null``. If null by default is true, nullable must be true. If null by default is false, nullable could be either.
``unique-by`` indicates whether duplicates can be permitted in the list.
ValueSpec Type:
.. code::
type: object
name: String
description: Option<String>
changeWarning: Option<String>
nullable: Boolean
null-by-default: Boolean
display-as: Option<String>
unique-by: UniqueBy
spec: ConfigSpec
type UniqueBy = null | string | { any: UniqueBy[] } | { all: UniqueBy[] }
Example:
.. code:: yaml
type: object
name: Advanced
description: Advanced settings for Bitcoin Proxy
nullable: false
spec:
tor-only:
type: boolean
name: Only Tor Peers
description: Use Tor for all peer connections
default: false
peer-timeout:
type: number
name: Peer Message Timeout
description: How long to wait for a response from a peer before failing
nullable: false
integral: true
units: Seconds
range: "[0, *)"
default: 30
max-peer-age:
type: number
name: Maximum Peer Age
description: How long to wait before refreshing the peer list
nullable: false
integral: true
units: Seconds
range: "[0, *)"
default: 300
max-peer-concurrency:
type: number
name: Maximum Peer Concurrency
description: How many peers to reach out to concurrently for block data
nullable: true
integral: true
range: "[1, *)"
default: 1
.. _string:
String
^^^^^^
There are various options for string values. They can optionally be marked as copyable or masked, such as for passwords, which will reflect the UI element display. A pattern, expressed in regex, can be denoted. If it exists, this field requires both the pattern type (ie. Regex) and pattern description (ie. an explanation of the pattern requirements).
If the default type is ``Entropy``, the charset can optionally specify an inclusive ranged character set (ie. "a-f,0-9").
ValueSpec Type:
.. code::
type: string
name: String
description: Option<String>
changeWarning: Option<String>
copyable: Option<boolean>
masked: Option<boolean>
nullable: Boolean
default: String | Entropy
pattern: Option<Regex>
pattern-description: Option<String>
Entropy Type:
.. code::
charset: Option<String>
len: integer
Examples:
.. code::
color:
type: string
name: Color
description: Color value for the Lightning Network
nullable: false
pattern: "[0-9a-fA-F]{6}"
patternDescription: |
Must be a valid 6 digit hexadecimal RGB value. The first two digits are red, middle two are green and final two are
blue
default:
charset: "a-f,0-9"
len: 6
password:
type: string
name: Password
description: The password for the RPC User
nullable: false
copyable: true
masked: true
default:
charset: "a-z,A-Z,0-9"
len: 22
.. _pointer:
Pointer
^^^^^^^
The pointer type *points* to a config value on another service installed on EmbassyOS (ie. app subtype) or to the EmbassyOS system (ie. system subtype). When pointing to another service, the ``index`` field indicates the path to the desired config variable.
ValueSpec Type:
.. code::
type: pointer
name: String
description: Option<String>
changeWarning: Option<String>
subtype: app | system
app-id: String (*always* kebab case)
target: AppPointerSpecVariants | SystemPointerSpecVariants
index: Option<String> (dependent on target being AppPointerSpecVariants)
AppPointerSpecVariants = LanAddress | TorAddress | TorKey | Config
SystemPointerSpecVariants = HostIp
Example:
.. code::
user:
type: pointer
name: RPC Username
description: The username for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.username"
.. _union:
Union
^^^^^
This type describes a necessary dependency. Multiple variants can be expressed to enable the user the option to connect to another service (internal dependency) or outside source (external dependency).
For example, the Bitcoin Proxy service is united with an instance of Bitcoin. Three variants are defined: internal, external, and a quick connect. In this case, internal refers to the Bitcoin Core instance running on EmbassyOS, and defines the RPC credentials necessary for connecting; external refers to a Bitcoin Core node running on a different device, and defines the RPC credentials necessary for connecting; quick connect refers to yet another method of connecting to a Bitcoin Core node, optimized for convenience.
Default is required and corresponds to one of the variants.
``Tag`` is the key that will be rendered on the UI element.
ValueSpec Type;
.. code::
type: union
name: String
description: Option<String>
changeWarning: Option<String>
default: Boolean
tag: Tag
variants: Map<String, ConfigSpec>
display-as: Option<String>
unique-by: any | all | exactly | notUnique
Tag Type:
.. code::
id: String
name: String
description: Option<String>
variant-names: Map<String, String>
.. _example_config_spec:
Example:
.. code:: yaml
bitcoind:
type: union
name: Bitcoin Core
description: The Bitcoin Core node to connect to
tag:
id: type
name: Type
description: |
- Internal: The Bitcoin Core service installed to your Embassy
- External: A Bitcoin Core node running on a different device
- Quick Connect: A Quick Connect URL for an unpruned Bitcoin Core node
variant-names:
internal: Internal
external: External
quick-connect: Quick Connect
default: internal
variants:
internal:
address:
type: pointer
name: Local Address
description: The LAN IP address of your Bitcoin Core service
subtype: app
app-id: bitcoind
target: lan-address
user:
type: pointer
name: RPC Username
description: The username for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.username"
password:
type: pointer
name: RPC Password
description: The password for the RPC user for Bitcoin Core
subtype: app
app-id: bitcoind
target: config
index: "rpc.password"
external:
addressext:
type: string
name: Public Address
description: The public address of your Bitcoin Core RPC server
nullable: false
userext:
type: string
name: RPC Username
description: The username for the RPC user on your Bitcoin Core RPC server
nullable: false
passwordext:
type: string
name: RPC Password
description: The password for the RPC user on your Bitcoin Core RPC server
nullable: false
quick-connect:
quick-connect-url:
type: string
name: Quick Connect URL
description: The Quick Connect URL for your Bitcoin Core RPC server
nullable: false
pattern: 'btcstandup://[^:]*:[^@]*@[a-zA-Z0-9.-]+:[0-9]+(/(\?(label=.+)?)?)?'
patternDescription: Must be a valid Quick Connect URL. For help, check out https://github.com/BlockchainCommons/Gordian/blob/master/Docs/Quick-Connect-API.md
.. _config_rules:
Config Rules
============
This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules.
A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser.
They follow the `BackusNaur <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ meta-syntax for writing rules.
Rules are composed of two main concepts:
* Variables - accessor into a configuration
* Terms - either a variable or type literal (ie. a boolean term is a boolean variable, a boolean expression, or a comparison operation between numbers or strings)
Variables can be booleans, numbers, or strings, and have a different syntax depending on the type. These type annotations check your config rules against your config spec and throw an error if invalid.
- ``?`` - Casts to boolean value. If the value is not a boolean, this notes whether or not the value is null.
- ``#`` - Treat the value as a number. If it is not a number, the value will be parsed as NaN. String numbers are not currently supported.
- ``'`` - Cast the value into a string. Applies to any value except for an object or a list.
- ``!`` - Equals not.
.. note::
Config rules are processed in order.
If application does not satisfy a rule, a set of suggestions should be provided. These suggestions are in the form of the operation to preform:
- ``Set`` - set the value
- ``Push`` - add to the value (such as to a list)
- ``Delete`` - delete the value
.. code:: typescript
enum SuggestionVariant = Set | Delete | Push
interface Set {
var: String, // fully qualified path without typecast
// one of the following three variants are required
to: Option<String> // a string expression, use when tying another config value
to-value: Option<String>
to-entropy: Option<{
charset: String (eg. 'a-z,A-Z,0-9')
len: Number
}>
}
interface Delete {
src: String, // path to key - removes if in a list
}
interface Push {
to: String,
value: String, // string literal of value to be set
}
Set Examples:
.. code:: yaml
- SET:
# the key in config you want to set
var: 'users.[first(item => ''item.name = "c-lightning")].password'
# the value in config that you will set
to-entropy:
charset: "a-z,A-Z,0-9"
len: 22
- SET:
var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks'
to-value: true
Push Examples:
.. code:: yaml
- PUSH:
to: "users"
value:
name: c-lightning
allowed-calls: []
- PUSH:
to: 'users.[first(item => ''item.name = "c-lightning")].allowed-calls'
value: "getnetworkinfo"
Full example from `c-lightning manifest <https://github.com/Start9Labs/c-lightning-wrapper/blob/master/manifest.yaml>`_:
.. code:: yaml
config:
- rule: '''users.*.name = "c-lightning"'
description: 'Must have an RPC user named "c-lightning"'
suggestions:
- PUSH:
to: "users"
value:
name: c-lightning
allowed-calls: []
- SET:
var: 'users.[first(item => ''item.name = "c-lightning")].password'
to-entropy:
charset: "a-z,A-Z,0-9"
len: 22
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,40 +0,0 @@
.. _service_docker:
******************
Service Dockerfile
******************
Dockerfile
==========
This purpose of the Dockerfile is to define how to build the image for the service. It declares the environment and building stages.
The Dockerfile is responsible for mounting the service application to whatever volume the manifest specifies, typically ``/root/.<service-id>``.
Since the build requires specific arm runtime environments, these base images can be imported into the Dockerfile as a starting point so the base system does not need to be completely redefined. This enables importing a specific build environment version that encapsulates any necessary libraries for running the service build, eg. golang, rust.
For instance:
``FROM alpine:3.12``
``FROM arm32v7/alpine``
``FROM arm32v7/golang:alpine``
We recommended using ``alpine`` since it produces the smallest image. We try to keep the image under 100MB when possible.
Entry-point
===========
The ``docker_entrypoint.sh`` defines what to do when the service application starts.
It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands for EmbassyOS.
Example
=======
The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Dockerfile>`_ features a well defined Dockerfile, for example.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,44 +0,0 @@
.. _service_pacakge:
***********************
Service Packaging Guide
***********************
Welcome! If you are here, you are interested in becoming part of the mission to change the future of personal computing. This guide will take you through the process of packaging a service for EmbassyOS, a novel, self-hosted, sovereign computing platform.
A service in this context is any open source project that has been bundled into the appropriate format to run on EmbassyOS. By configuring and packaging a project according to this guide, it can be installed on EmbassyOS with no command line or technical expertise required. This opens up an entire platform for self-hosted software to run independent of third parties in a completely private and sovereign way for all individuals.
This guide is technical, but breaks down the steps for deployment. If you have any feedback or questions concerning this guide, please don't hesitate to `reach out <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ or submit a pull request with alterations.
To start, you will need to acquire EmbassyOS for testing the packaged service. This can be done by:
- building from `source <https://github.com/Start9Labs/embassy-os/blob/master/CONTRIBUTING.md#setting-up-your-development-environment>`_
- following the :ref:`DIY <diy>` guide
- :ref:`purchasing <purchasing>` the ready to run personal server
While you are waiting to receive or assemble a device, you can begin the process of packaging a project. The sections below outline these steps in detail.
Happy building!
.. toctree::
:maxdepth: 1
Overview <overview>
Wrapper <wrapper>
Manifest <manifest>
Docker <docker>
Makefile <makefile>
Config <config>
Properties <properties>
Instructions <instructions>
Backups <backups>
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.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,23 +0,0 @@
.. _service_instructions:
************************************
Service Instructions & Documentation
************************************
Within each wrapper repository should exist a ``docs`` directory. This folder should include any pertinent documentation, instructions, external integrations, or other details about the service that users or developers might find relevant.
If an ``instructions.md`` file is included, this markdown formatted file will be rendered in the "Instructions" tab within the service detail menu on EmbassyOS:
.. figure:: /_static/images/service/bitcoin_instructions.png
:width: 80%
:alt: Bitcoin Instructions
Example
=======
The `bitcoind wrapper <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs>`_ demonstrates a good use of instructions and external integrations.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,30 +0,0 @@
.. _service_makefile:
****************
Service Makefile
****************
.. note::
*This file is optional*
A Makefile serves as a convenience for outlining the build. This helps streamline additional developer contributions to the project. Please reference the GNU `documentation <https://www.gnu.org/software/make/manual/html_node/Introduction.html>`_ for implementation details.
An alternative to using ``make`` is to use the `nix <https://nixos.wiki/wiki/Nix>`_ specification.
This purpose of this file is to:
- Read the docker container and build the project
- Build all prerequisites for running the docker file
- Build all dependencies
- Package ``config_rules.yaml``, ``config_spec.yaml``, ``manifest.yaml``, and ``image.tar`` into an ``.s9pk`` extension by invoking ``appmgr``.
Example
=======
The `LND wrapper <https://github.com/Start9Labs/lnd-wrapper/blob/master/Makefile>`_ features a well defined Makefile, for example.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,352 +0,0 @@
.. _service_manifest:
****************
Service Manifest
****************
Overview
========
This file describes the service and it's requirements. It is used to:
- create a listing in the marketplace
- denote any installation considerations
- define dependency requirements
Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information.
For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/blob/master/manifest.yaml#L28>`_ around restoration since data will be overwritten.
There is nothing you need to do as a developer to set up Tor for running a service. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated when the service is installed. Just define the port and which version of Tor the service needs in this manifest file! You do, however, need to ensure the service is in fact capable of running over Tor.
The manifest is also responsible for outlining service :ref:`dependencies <dependencies>`. By defining rules using the :ref:`EmbassyOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. EmbassyOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
Formatting
==========
- Serialization language:``.yaml``
- Case style: ``kebab-case``
Type definitions
================
Below are the types and sub-type definitions, with necessary elaborations. Any item that contains ``Option<>`` is an optional field.
.. code:: yaml
# manifest version compatibility ie. v0 (this is currently the only option)
compat: v0
# service id, used for uniqueness and BE identification ie. bitcoind
id: String
# version number of the release conforming to the semantic versioning scheme
version: String
# display name of service
title: String
# an object containing a short and long description of the service. TODO character lengths
description:
short: String
long: String
# a link to the release tag notes in GitHub, or a short description TODO character length
release-notes: String
# a notification message that should caution the user with any service particularities, eg. beta tech
install-alert: Option<String>
# a notification message warning users of potential problems with uninstalling, such as dependency failures or data loss
uninstall-alert: Option<String>
# a notification message containing warning or details about backup restoration
restore-alert: Option<String>
# denoting the existence of instructions.md
has-instructions: Boolean
# required semver version range of EmbassyOS to run service eg. ">=1.0.0"
os-version-required: VersionReq
# recommended semver version range of EmbassyOS to run service eg."^1.0.0"
os-version-recommended: VersionReq
# a list of objects of ports to run the service on localhost and tor
ports:
- internal: String
tor: String
# currently only tar is supported
image:
type: String
# shared memory container size
shm-size-mb: Option<usize>
# path to mount the image on the volume, ie: /root/bitcoind
mount: String
# read only data exposed to dependencies (path is relevant to mount)
public: Option<String>
# shared filesystem segment with each of your dependencies (path is relevant to mount)
shared: Option<String>
# deprecated - will default to an empty vector
assets: []
# version of tor support, eg. v2, v3
hidden-service-version: String
# A map of dependent services, see below for more details
dependencies: Dependencies
.. _dependencies:
Dependencies
============
Many services depend on other libraries and services on EmbassyOS (such as Bitcoin), sometimes even a particular version of those services, which need to be specified by the developers so that EmbassyOS can handle installing these dependencies under the hood.
The key of each field in the dependencies object is the lowercase, kebab-case app ID of the service that is depended on. 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.
Let's take this snippet for example:
.. code:: yaml
...
dependencies:
btc-rpc-proxy:
version: "^0.1.0"
optional: Can configure an external bitcoin node.
description: Required for fetching validated blocks.
config:
- rule: '''users.*.name = "c-lightning"'
description: 'Must have an RPC user named "c-lightning"'
suggestions:
- PUSH:
to: 'users'
value:
name: c-lightning
...
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`
The service ``btc-rpc-proxy`` is a dependency of the service ``c-lightning``. ``c-lightning`` requires it to be installed at a version >=0.1.0 <0.2.0. There exists a rule that states the config option ``user.name`` must be equal to "c-lightning". If this value does not exist for ``user.name`` when accessed, ``PUSH`` the value "c-lighting" to the field. This all takes place during the initial service configuration, before the service is started for the first time.
.. note::
Dependency config rules are processed in order.
Type definitions
----------------
Types for ``manifest.yaml`` fields:
.. code:: typescript
interface Dependencies [{
serviceId: DepInfo
}]
interface DepInfo {
version: String // ie. 0.11.1.1
optional?: String,
description?: String,
config: [ConfigRule],
],
}
interface ConfigRule {
rule: String, // ie. 'users.*.name = "lnd"
description: String,
suggestions: [SuggestionVariant]
}
interface SuggestionVariant {
SET: {
var: String,
to: SetVariant,
},
DELETE: {
src: String,
},
PUSH: {
to: String,
value: Value,
},
}
interface SetVariant {
to: Option<String>,
to-value: Option<Value>, // ie. true/false
to-entropy: Option<{
charset: String // ie. 'a-z,A-Z,0-9'
len: number
}>
}
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`
Examples
--------
Actual ``manifest.yaml`` files for existing services:
LND
^^^
.. code:: yaml
compat: v0
id: lnd
version: 0.11.1.1
title: Lightning Network Daemon
description:
short: "A complete implementation of a Lightning Network node by Lightning Labs"
long: "LND fully conforms to the Lightning Network specification (BOLTs). BOLT stands for: Basis of Lightning Technology. In the current state lnd is capable of: creating channels, closing channels, managing all channel states (including the exceptional ones!), maintaining a fully authenticated+validated channel graph, performing path finding within the network, passively forwarding incoming payments, sending outgoing onion-encrypted payments through the network, updating advertised fee schedules, and automatic channel management (autopilot)."
release-notes: https://github.com/lightningnetwork/lnd/releases/tag/v0.11.1-beta
ports:
- internal: 8080
tor: 8080
- internal: 9735
tor: 9735
- internal: 9911
tor: 9911
- internal: 10009
tor: 10009
image:
type: tar
mount: /root/.lnd
public: public
has-instructions: true
os-version-required: ">=0.2.8"
os-version-recommended: ">=0.2.8"
install-alert: |
READ CAREFULLY! LND and the Lightning Network are considered beta software. Please use with caution and do not risk more money than you are willing to lose. We encourage frequent backups. If for any reason, you need to restore LND from a backup, your on-chain wallet will be restored, but all your channels will be closed and their funds returned to your on-chain wallet, minus fees. It may also take some time for this process to occur.
uninstall-alert: "READ CAREFULLY! Uninstalling LND will result in permanent loss of data, including its private keys for its on-chain wallet and all channel states. Please make a backup if you have any funds in your on-chain wallet or in any channels. Recovering from backup will restore your on-chain wallet, but due to the architecture of the Lightning Network, your channels cannot be recovered. All your channels will be closed and their funds returned to your on-chain wallet, minus fees. \n"
restore-alert: |
Restoring LND will overwrite its current data, including its on-chain wallet and channels. Any channels opened since the last backup will be forgotten and may linger indefinitely, and channels contained in the backup will be closed and their funds returned to your on-chain wallet, minus fees.
assets: []
hidden-service-version: v3
dependencies:
btc-rpc-proxy:
version: "^0.2.4"
optional: Can alternatively configure an external bitcoin node.
description: Used to fetch validated blocks.
config:
- rule: '''users.*.name = "lnd"'
description: 'Must have an RPC user named "lnd"'
suggestions:
- PUSH:
to: "users"
value:
name: lnd
allowed-calls: []
- SET:
var: 'users.[first(item => ''item.name = "lnd")].password'
to-entropy:
charset: "a-z,A-Z,0-9"
len: 22
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getinfo"'
description: 'RPC user "lnd" must have "getinfo" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getinfo"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getbestblockhash"'
description: 'RPC user "lnd" must have "getbestblockhash" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getbestblockhash"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "gettxout"'
description: 'RPC user "lnd" must have "gettxout" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "gettxout"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockchaininfo"'
description: 'RPC user "lnd" must have "getblockchaininfo" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getblockchaininfo"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "sendrawtransaction"'
description: 'RPC user "lnd" must have "sendrawtransaction" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "sendrawtransaction"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockhash"'
description: 'RPC user "lnd" must have "getblockhash" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getblockhash"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblock"'
description: 'RPC user "lnd" must have "getblock" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getblock"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getblockheader"'
description: 'RPC user "lnd" must have "getblockheader" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getblockheader"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "estimatesmartfee"'
description: 'RPC user "lnd" must have "estimatesmartfee" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "estimatesmartfee"
- rule: '''users.[first(item => ''item.name = "lnd")].allowed-calls.* = "getnetworkinfo"'
description: 'RPC user "lnd" must have "getnetworkinfo" enabled'
suggestions:
- PUSH:
to: 'users.[first(item => ''item.name = "lnd")].allowed-calls'
value: "getnetworkinfo"
- rule: 'users.[first(item => ''item.name = "lnd")].fetch-blocks?'
description: 'RPC user "lnd" must have "Fetch Blocks" enabled'
suggestions:
- SET:
var: 'users.[first(item => ''item.name = "lnd")].fetch-blocks'
to-value: true
bitcoind:
version: "^0.21.0"
optional: Can alternatively configure an external bitcoin node.
description: Used to subscribe to new block events.
config:
- rule: "zmq-enabled?"
description: "Must have an ZeroMQ enabled"
suggestions:
- SET:
var: "zmq-enabled"
to-value: true
Cups
^^^^
.. code:: yaml
compat: v0
id: cups
version: "0.3.6"
title: "Cups Messenger"
description:
short: "Real private messaging"
long: "Cups is a private, self-hosted, peer-to-peer, Tor-based, instant messenger. Unlike other end-to-end encrypted messengers, with Cups on the Embassy there are no trusted third parties."
release-notes: |
Features
- Adds instructions defined by EmbassyOS 0.2.4 instructions feature
ports:
- internal: 59001
tor: 59001
- internal: 80
tor: 80
image:
type: tar
mount: /root
has-instructions: true
os-version-required: ">=0.2.4"
os-version-recommended: ">=0.2.4"
assets:
- src: httpd.conf
dst: "."
overwrite: true
- src: www
dst: "."
overwrite: true
hidden-service-version: v3
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,103 +0,0 @@
.. _service_package_overview:
************************
Service Package Overview
************************
There are several main components that comprise a service package for EmbassyOS. This overview will introduce them and following sections will dive into technical specifics.
First, let's get your system setup with the necessary software dependencies.
Environment Setup
=================
At minimum, ``docker``, ``docker-buildx``, and ``appmgr`` are required. The rest of the recommendations serve to optimize the build process.
Recommended Dependencies
------------------------
`docker <https://docs.docker.com/get-docker>`_
`docker-buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
`appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_
`cargo <https://doc.rust-lang.org/cargo/>`_
`yq (version 4) <https://mikefarah.gitbook.io/yq>`_
`make <https://www.gnu.org/software/make/>`_
`musl <https://github.com/Start9Labs/rust-musl-cross>`_
Package Components
==================
Image
-----
Each service boils down to a Docker image. We're not going to dive into Docker specifics in this guide, since there exists tons of `resources <https://docs.docker.com/>`_ for developing with this containerization tool.
Because the service ultimately runs on a Raspberry Pi, the created Docker image should be a snapshot of an arm based linux environment. The service image is then mounted to the EmbassyOS image during installation. This path is defined in the :ref:`manifest <service_manifest>` configuration file.
The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
Volume
------
Each service application gets a volume allocated to it by EmbassyOS. All service application data is stored in this directory and is persisted across updates.
The volume directory (for seeding data into the volume) is typically: ``/root/volumes/<service-id>``.
.. warning::
Any files that are in the image at the volume path will be overwritten when a backup restore occurs.
Dependencies
------------
When it comes to running your own server, managing dependencies is perhaps the most difficult part. The term "dependency hell" emerged from this sentiment. Even the best developers have lost significant amounts of time trying to find, correct, or clarify documentation for dependencies or dependency configuration. Individuals who manage their own servers have specific technical skills and are willing to devote the time and effort necessary to maintain them. Companies have entire departments dedicated to this feat.
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: *its novel*. This has never been done before.
The key to making the system work is a new, domain-specific-language (DSL) and set of standards that are used by developers to define the rules and requirements of their services. Run in the context of EmbassyOS, these rules and requirements appear as simple UI elements, such as inputs, toggles, and drop downs, and they are enforced by validations and clear user instructions. Using this system, what previously required involved time and expertise, can now be done by anyone in a matter of seconds.
This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <dependencies>` key in the service manifest.
Manifest
--------
This file describes the service and its requirements. It is used to:
- create a listing in the marketplace
- denote any installation considerations
- define dependency requirements
Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information about the particularities of the service.
For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/blob/master/manifest.yaml#L28>`_ around restoration since data will be overwritten.
There is nothing you need to do as a developer to enable the service to run over Tor. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated and an Nginx server configured (if a client application) when the service is installed. Just define which version of Tor your service needs in this manifest file!
Config
------
Most self-hosted applications require the user to tell the app how to behave using a config file in a specific format, environment variables, command-line arguments, or some combination of these inputs. One of the coolest features of EmbassyOS is that, when packaged correctly, the app's :ref:`configuration <service_config>` will be available to the user as a slick GUI that always produces a valid configuration no matter how little experience or skill the user has.
With EmbassyOS, this means a service wrappers' configuration requires a particular format and rule structure to ensure it integrates smoothly with the user interface. This format enables clean handling of improper values and configuration dependencies.
.s9pk Bundle
------------
The configuration and manifest files get bundled into the ``.s9pk`` package, which is `built using appmgr <https://github.com/Start9Labs/embassy-os/tree/master/appmgr>`_. Each new version release should include the updated version of these files re-bundled into a new binary. This is the file that will be downloaded from the marketplace. Upon user initiation, EmbassyOS then un-packages and installs the service.
Hello World Example
-------------------
For reference, the `Hello world <https://github.com/Start9Labs/hello-world-wrapper>`_ repository should be used as an example. A project template can be cloned using the "Use this template" button in GitHub.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,25 +0,0 @@
.. _service_properties:
******************
Service Properties
******************
The output of this step is a file titled ``stats.yaml``. This file contains a mapping of the values that will be displayed in the ``Properties`` section in a service's menu.
.. figure:: /_static/images/service/service_properties.png
:width: 80%
:alt: Service Properties
Service Properties Tab
Due to the fact that config variables are only available when the service is running, this file can only be populated at runtime. In services Start9 has wrapped or created, we typically handle this in ``configurator/src/main.rs``. This file is essentially a script that acquires the necessary values at runtime from config (eg. ``/root/.lnd/start9/config.yaml``), and dynamically populating them to the ``stats.yaml`` file, marking each value with the appropriate keys for UI display (ie. masked or copyable). Running the configurator is typically included in the ``docker_entrypoint.sh`` file.
Example
=======
A good example of the configurator producing the ``stats.yaml`` file can be found `here <https://github.com/Start9Labs/lnd-wrapper/blob/master/configurator/src/main.rs>`_.
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`

View File

@@ -1,42 +0,0 @@
.. _service_wrapper:
***************
Service Wrapper
***************
Each service is bound with a wrapper repository, which contains everything you need to build a service.
The purpose of this repo is:
- Denote any dependencies required to run and build the project
- To define the necessary, ``config_rules.yaml``, ``config_spec.yaml`` and ``manifest.yaml`` options
- To build the project into the ``.s9pk`` format digestible to EmbassyOS
- Link to the source project as a git submodule
- Define the docker file for running the project on EmbassyOS
- Provide documentation for the project, especially user runbook instructions
- symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root, if included
File Structure
==============
The project structure should be used as a model:
.. code-block:: bash
├── Dockerfile
├── Makefile (optional)
├── README.md
├── config_rules.yaml
├── config_spec.yaml
├── <submodule_project_dir>
├── docker_entrypoint.sh
├── docs
│ └── instructions.md
└── manifest.yaml
Submodule
==========
`Git submodules <https://www.git-scm.com/book/en/v2/Git-Tools-Submodules>`_ allow use of another project while in the working project directory. Setting up this feature enables linking of the source service repository so that its context is available.
Run ``git submodule add <link_to_source_project>``

View File

@@ -1,158 +0,0 @@
.. _diy:
*********
DIY Guide
*********
.. figure:: /_static/images/diy/pi.png
:width: 40%
:alt: Raspberry Pi
Raspberry Pi Board
By popular demand, we are pleased to present this "Do it Yourself" (DIY) guide for the Start9 Embassy personal server!
.. warning:: This DIY guide has directions for EmbassyOS versions 0.2.x and versions 0.3.x. When 0.3.0 launches it will REQUIRE hardware updates, which you can find `here <https://start9.com/eos-0.3.0>`__. Please keep in mind that version 0.3.x is not yet available for purchase!! Please stay tuned to our community channels for updates.
Motivation
==========
There are four reasons you might prefer to build your own Embassy instead of purchasing one from us.
#. You already own the necessary hardware and would like to re-purpose it.
#. You live outside the US and want to save on shipping costs.
#. You do not trust Start9's supply chain.
#. You do not want to share your shipping address.
#. You just like building things.
Building EmbassyOS Versions 0.2.x
=================================
Hardware: Components
--------------------
#. `Raspberry Pi 4B (8GB) <https://raspberrypi.org/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb>`_
#. `Power supply for Raspberry Pi 4B <https://raspberrypi.org/products/type-c-power-supply/>`_
#. Case for Raspberry Pi 4B (`passive cooling recommended <https://www.amazon.com/Geekworm-Raspberry-Aluminum-Passive-Heatsink/dp/B07Z6FYHCH/>`_ `*`)
#. `High endurance microSD <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (recommended 128GB or more)
#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
#. Ethernet cable
#. MicroSD → USB adapter (or you may have a microSD port on your computer)
`*` If you use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
Hardware: Assembly Instructions
-------------------------------
#. Insert mini speaker/buzzer into GPIO pins 6/8/10/12 with the word "speaker" facing out, `away from the board`.
.. figure:: /_static/images/diy/pins.png
:width: 60%
:alt: Speaker board spec
That's it. Place the Raspberry Pi 4 board (with speaker attached), into its case.
Getting EmbassyOS: Purchasing
-----------------------------
You can purchase EmbassyOS `here <https://store.start9.com/collections/embassy/products/embassyos-software-download>`_. This is by far the easiest path to get up and running.
Depending on your Internet speed, the download should take between 5 and 30 minutes.
Getting EmbassyOS: Building from Source
---------------------------------------
If you have the proper tooling and are comfortable using the command line, you can build EmbassyOS from `source <https://github.com/Start9Labs/embassy-os>`_, which is made available under the `Start9 Personal Use License <https://start9.com/license>`_.
Thanks to our community members who have kindly put together these guides!
* A comprehensive and user friendly guide by `Bitcoin Mechanic <https://medium.com/@lex10/building-my-wife-an-embassy-from-scratch-19cb87193fb2>`_
* A technically focused guide by `t0mmysm1th <https://github.com/t0mmysm1th/embassy-os/blob/master/BuildGuide.md>`_
Installing EmbassyOS
--------------------
Whether you purchase EmbassyOS from us or build it yourself, you need to flash it onto a microSD card.
#. Download `balenaEtcher <https://www.balena.io/etcher/>`_ onto your Mac, Windows, or Linux computer.
#. Insert the microSD card into your computer, either directly or using an adapter.
#. Open balenaEtcher.
#. Click `Select Image`, then find and select your copy of EmbassyOS.
#. Click `Select Target`, then find and select your micro SD card.
#. Click `Flash!` You may be asked to (1) approve the unusually large disk target or (2) enter your password. Both are normal.
.. figure:: /_static/images/diy/balena.png
:width: 60%
:alt: Balena Etcher Dashboard
#. Once the image is flashed and verified, you may remove the micro SD, insert it into your Embassy, and power up the device.
#. The Embassy is now ready for use, and you may following the normal :ref:`setup <initial-setup>` instructions. ``*``
``*`` The first time you power it on, your Embassy will make more noises than future attempts, and it may take several minutes to finally complete.
Building EmbassyOS Versions 0.3.x
=================================
Hardware: Components
--------------------
#. `Raspberry Pi 4B (8GB) <https://raspberrypi.org/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb>`_
#. `Power supply for Raspberry Pi 4B <https://raspberrypi.org/products/type-c-power-supply/>`_ Make sure this is at minimum 15w and 3.5a.
#. Case for Raspberry Pi 4B (`passive cooling recommended <https://www.amazon.com/Geekworm-Raspberry-Aluminum-Passive-Heatsink/dp/B07Z6FYHCH/>`_ `*`)
#. A `16GB microSD card <https://amazon.com/SanDisk-Endurance-microSDXC-Adapter-Monitoring/dp/B07NY23WBG/>`_ (no need for bigger). If you have ABSOLUTELY NO data to migrate, you may choose to re-use the card already in your Embassy.
#. `GPIO mini speaker/buzzer <https://www.amazon.com/Corporate-Computer-Motherboard-Internal-Speaker/dp/B01527H4W2/>`_ (These often sell out, please let us know if this link needs to be refreshed)
#. Ethernet cable
#. MicroSD → USB adapter (or you may have a microSD port on your computer)
#. An external drive (1TB minimum, 2TB SSD recommended), or an `internal drive <https://www.amazon.com/Crucial-MX500-NAND-SATA-Internal/dp/B078211KBB>`_ with an `USB enclosure <https://www.amazon.com/gp/product/B07T9D8F6C>`_, as sold with our upgrade kits. MUST CONNECT OVER USB 3.0
`*` If you use a fan, **DO NOT** use the official Raspberry Pi fan, as it requires the same GPIO pins as the audio speaker. Instead, we recommend `this fan <https://www.amazon.com/Raspberry-iUniker-30x30x7mm-Brushless-RetroFlag/dp/B076H3TKBP/>`_.
Hardware: Assembly Instructions
-------------------------------
#. Insert mini speaker/buzzer into GPIO pins 6/8/10/12 with the word "speaker" facing out, `away from the board`.
.. figure:: /_static/images/diy/pins.png
:width: 60%
:alt: Speaker board spec
#. Place the Raspberry Pi 4 board (with speaker attached), into its case.
#. Plug in the external drive to one of the USB 3.0 (blue) slots
Getting EmbassyOS: Purchasing
-----------------------------
You can purchase EmbassyOS `here <https://store.start9.com/collections/embassy/products/embassyos-software-download>`_. This is by far the easiest path to get up and running.
Depending on your Internet speed, the download should take between 5 and 30 minutes.
Getting EmbassyOS: Building from Source
---------------------------------------
A detailed build guide will be available around the time of the v0.3.0 release (or now, if you snoop around our GitHub long enough).
Installing EmbassyOS
--------------------
Whether you purchase EmbassyOS from us or build it yourself, you need to flash it onto a microSD card.
#. Download `balenaEtcher <https://www.balena.io/etcher/>`_ onto your Mac, Windows, or Linux computer.
#. Insert the microSD card into your computer, either directly or using an adapter.
#. Open balenaEtcher.
#. Click `Select Image`, then find and select your copy of EmbassyOS.
#. Click `Select Target`, then find and select your micro SD card.
#. Click `Flash!` You may be asked to (1) approve the unusually large disk target or (2) enter your password. Both are normal.
.. figure:: /_static/images/diy/balena.png
:width: 60%
:alt: Balena Etcher Dashboard
#. Once the image is flashed and verified, you may remove the micro SD, insert it into your Embassy, and power up the device.
#. The Embassy is now ready for use, and you may following the normal :ref:`setup <initial-setup>` instructions. ``*``
``*`` The first time you power it on, your Embassy will make more noises than future attempts, and it may take several minutes to finally complete.

View File

@@ -1,13 +0,0 @@
************
Introduction
************
Embassy is a new kind of personal computer - one that sits quietly on your shelf and runs all day and night. It has no screen and no keyboard. You access your Embassy from anywhere in the world in total, trustless privacy, simply by visiting its unique Tor address (.onion URL) right from the browser.
Embassy is composed of commonly available hardware components that can be sourced and assembled by anyone, anywhere, for a marginal fee. Embassy is powered by EmbassyOS, the open-source operating system by Start9.
So, what do you do with your Embassy? You use it to run services: Bitcoin, Lightning, personal cloud storage, P2P messaging, password management, etc. The list of available services is growing quickly and will eventually encompass the entirety of open-source, self-hosted software.
Every communication between you and your Embassy is end-to-end encrypted and onion routed over the Tor network. All services are open-source and self-hosted, meaning there are no trusted third parties of any kind.
To get an Embassy, you can :ref:`purchase<purchasing>` one directly from Start9, or you can :ref:`build one yourself<diy>`.

View File

@@ -1,9 +0,0 @@
.. _purchasing:
**********
Purchasing
**********
For maximum convenience, you can purchase an Embassy device directly from Start9 through our `Shopify Store <https://store.start9.com>`_. The device comes in a beautiful box, fully-assembled, and pre-installed with the latest version of EmbassyOS. We do our own hardware assembly and fulfillment, and we only collect the minimal information necessary to fulfill your order. And yes, we accept Bitcoin.
If you prefer to build your own Embassy, you can follow the :ref:`DIY Guide <diy>`.

View File

@@ -1,132 +0,0 @@
.. title:: Start9 Documentation
.. raw:: html
<div class="landing landing--floating">
.. hero-box::
:title: Welcome to the Start9 Documentation
:button_icon: scylla-icon scylla-icon--monitoring
:button_url: https://docs.start9.com/getting-started/introduction/
:button_text: Start here
:image: /_static/img/icons/docs_info.png
Here you will find guidance and information about the Start9 Embassy personal server and its operating system, EmbassyOS.
.. raw:: html
<div class="landing__content landing__content">
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Purchasing
:link: getting-started/purchasing
:icon: scylla-icon scylla-icon--bitcoin
:class: large-6
:anchor: Learn more
Learn about how you can purchase Start9 products.
.. topic-box::
:title: Videos
:link: https://www.youtube.com/channel/UCGEw4HJDvOn3Oy8ykR36P7Q
:icon: scylla-icon scylla-icon--webinars
:class: large-6
:anchor: Learn more
Check out our how to and informational videos.
.. topic-box::
:title: Support
:link: support
:icon: scylla-icon scylla-icon--support
:class: large-6
:anchor: Learn more
Read our FAQ and learn about platform concepts.
.. topic-box::
:title: DIY
:link: getting-started/diy
:icon: scylla-icon scylla-icon--integrations
:class: large-6
:anchor: Learn more
Get started yourself with our Do It Yourself guide
.. topic-box::
:title: About
:link: about
:icon: scylla-icon scylla-icon--about-team
:class: large-6
:anchor: Learn more
Explore Start9's mission and philosophy.
.. topic-box::
:title: Contribute
:link: contributing
:icon: scylla-icon scylla-icon--apps
:class: large-6
:anchor: Learn more
Learn about developing for EmbassyOS or contribute to packing services for the marketplace.
.. raw:: html
</div></div>
.. raw:: html
</div></div>
.. toctree::
:maxdepth: 2
:caption: Getting Started
:hidden:
getting-started/introduction
getting-started/purchasing
getting-started/diy
.. toctree::
:maxdepth: 2
:caption: User Manual
:hidden:
user-manual/initial-setup
user-manual/connecting
user-manual/general/index
user-manual/managing-services/index
.. toctree::
:maxdepth: 2
:caption: Misc Guides
:hidden:
misc-guides/available-services
misc-guides/bitcoin-cli
misc-guides/tor-os/index
misc-guides/tor-firefox/index
.. toctree::
:maxdepth: 2
:caption: Contributing
:hidden:
contributing/services/index
contributing/embassyos
.. toctree::
:maxdepth: 2
:caption: Support
:hidden:
support/FAQ/index
support/concepts
support/contact

View File

@@ -1,29 +0,0 @@
.. _available-services:
******************
Available Services
******************
A list of currently-available services for the Embassy.
Bitcoin-related services
========================
* `Bitcoin <https://github.com/Start9Labs/bitcoind-wrapper/tree/master/docs>`_
* `Bitcoin Proxy <https://github.com/Start9Labs/btc-rpc-proxy-wrapper/tree/master/docs>`_
* `Lightning Network Daemon (LND) <https://github.com/Start9Labs/lnd-wrapper/tree/master/docs>`_
* `c-lightning <https://github.com/Start9Labs/c-lightning-wrapper/tree/master/docs>`_
* `Ride the Lightning (RTL) <https://github.com/Start9Labs/ride-the-lightning-wrapper/tree/master/docs>`_
* `Spark Wallet <https://github.com/Start9Labs/spark-wallet-wrapper/tree/master/docs>`_
* `BTCPayServer <https://github.com/Start9Labs/btcpayserver-wrapper>`_
* `Sphinx Chat <https://sphinx.chat/>`_
Other services
==============
* `Bitwarden <https://github.com/Start9Labs/bitwarden-wrapper/tree/master/docs>`_
* `Burn After Reading <https://github.com/Start9Labs/burn-after-reading>`_
* `Cups <https://github.com/Start9Labs/cups-wrapper/tree/master/docs>`_
* `File Browser <https://github.com/Start9Labs/filebrowser-wrapper/tree/master/docs>`_
* `Mastodon <https://github.com/Start9Labs/mastodon-wrapper>`_
* `Embassy Pages <https://github.com/Start9Labs/embassy-pages-wrapper>`_

View File

@@ -1,26 +0,0 @@
.. _bitcoin-cli:
*****************
Using Bitcoin-Cli
*****************
Instructions for accessing the bitcoind service in order to issue commands directly.
.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.
1. First, you will need SSH access. Please see the :ref:`setup instructions <ssh-setup>` for details.
2. Access your Embassy and then you can interact with the bitcoind docker container using the following syntax::
sudo docker exec bitcoind bitcoin-cli COMMAND
.. admonition:: Example
sudo docker exec bitcoind bitcoin-cli getnetworkinfo
A list of possible commands can be found `here <https://chainquery.com/bitcoin-cli>`_.
You can also drop into a shell using::
sudo docker exec -it bitcoind bash
and then enter ``bitcoin-cli`` commands. When you are finished, simply type ``exit``.

View File

@@ -1,46 +0,0 @@
.. _firefox-tor-android:
**************************************
Setting up Firefox with Tor on Android
**************************************
.. warning::
This guide assumes you have completed :ref:`setting up Tor for Android<tor-android>`. Please visit this section before proceeding as it is required for Firefox to properly work with Tor.
Once Tor is setup on your system, you can proceed to setup Firefox:
1. Download `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta>`_ from the Play Store, or `Fennec <https://f-droid.org/en/packages/org.mozilla.fennec_fdroid/>`_ from F-Droid.
2. Next, download a `Proxy Auto Config` file that will use Orbot to resolve `.onion` URLs. We have one hosted `here <https://registry.start9labs.com/sys/proxy.pac>`_.
3. Navigate to ``about:config`` in the Firefox URL bar.
.. figure:: /_static/images/tor/about_config.png
:width: 50%
:alt: Firefox about config
4. You are going to have to change a few options in here. First, type ``network.proxy.type`` into the search bar, and set the value to ``2``.
.. figure:: /_static/images/tor/network_proxy_type.png
:width: 50%
:alt: Firefox network proxy type setting screenshot
5. Search for ``network.proxy.autoconfig_url``, and set the value to ``file:///storage/emulated/0/Download/proxy.pac``.
.. figure:: /_static/images/tor/autoconfig_url.png
:width: 50%
:alt: Firefox autoconfig url setting screenshot
6. Search for ``network.proxy.socks_remote_dns``, and set the value to ``true``.
.. figure:: /_static/images/tor/socks_remote_dns.png
:width: 50%
:alt: Firefox socks remote dns setting screenshot
7. Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
.. figure:: /_static/images/tor/firefox_whitelist_mobile.png
:width: 50%
:alt: Firefox whitelist onions screenshot
8. Restart Firefox, and youre all set! You should now be able to navigate to `.onion` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Password Manager <https://play.google.com/store/apps/details?id=com.x8bit.bitwarden&hl=en_US&gl=US>`_ native application.

View File

@@ -1,94 +0,0 @@
.. _firefox-tor-desktop:
**************************************
Setting up Firefox with Tor on Desktop
**************************************
.. warning::
This guide assumes you have completed :ref:`setting up Tor<running-tor>`. Please visit this section first before you proceed as it is required for Firefox to properly work with Tor.
1. Open Firefox.
2. Enter ``about:config`` in the URL bar. Accept any warnings that may appear about accessing advanced settings.
3. Search for ``dom.securecontext.whitelist_onions`` and set the value to ``true``.
.. figure:: /_static/images/tor/firefox_whitelist.png
:width: 80%
:alt: Firefox whitelist onions screenshot
4. Download a `Proxy Auto Config` file to inform Firefox how to use the Tor daemon running on your computer. You can get Start9's standard file by following the OS-specific instructions below:
Windows:
Click `here <https://registry.start9labs.com/sys/proxy.pac>`_ to get the file and save the file somewhere you wont delete it. Please remember the location you save the file in if you do not use our example location. For this example:
.. code-block::
C:\Program Files\Tor Browser\proxy.pac
Mac:
Open the ``Terminal`` App on your Mac. You can find it in your list of Applications. In the terminal, enter:
.. code-block::
brew install wget
And then:
.. code-block::
wget -P /usr/local/etc/tor https://registry.start9labs.com/sys/proxy.pac
Linux:
From a terminal, enter:
.. code-block::
sudo wget -P /etc/tor https://registry.start9labs.com/sys/proxy.pac
5. Now open your Firefox web browser, and select options (Windows), or preferences (Mac/Linux):
.. figure:: /_static/images/tor/firefox_options_windows.png
:width: 80%
:alt: Firefox options screenshot
Select :menuselection:``Settings --> Options``
6. Search for the term “proxy” in the search bar in the upper right, then select the button that says ``Settings…``:
.. figure:: /_static/images/tor/firefox_search.png
:width: 80%
:alt: Firefox search screenshot
7. This should open a menu that will allow you to configure your proxy settings. Select ``Automatic proxy configuration URL`` and paste in the path to your PAC file from earlier, prefixed with ``file://``. For example:
Windows:
.. code-block::
file://C:/Program Files/Tor Browser/proxy.pac
Mac:
.. code-block::
file:///usr/local/etc/tor/proxy.pac
Linux:
.. code-block::
file:///etc/tor/proxy.pac
8. Then, check the box labeled ``Proxy DNS when using SOCKS v5``:
.. figure:: /_static/images/tor/firefox_proxy.png
:width: 80%
:alt: Firefox proxy settings screenshot
9. Click ``OK`` and then restart Firefox for the changes to take effect.
10. Youre all set! You should now be able to navigate to ``.onion`` URLs in Firefox. This means you can bookmark Cups Messenger, and use your Bitwarden Tor address in the `Bitwarden Firefox Plugin <https://addons.mozilla.org/en-US/firefox/addon/bitwarden-password-manager/>`_.

View File

@@ -1,16 +0,0 @@
.. _configure_firefox_tor:
***************************
Configuring Firefox for Tor
***************************
.. warning::
This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
Once you have completed the above guide, select your device's operating system below:
.. toctree::
:maxdepth: 2
Desktop<desktop>
Mobile<mobile>

View File

@@ -1,9 +0,0 @@
.. _firefox-tor-ios:
**********************************
Setting up Firefox with Tor on iOS
**********************************
Unfortunately, Apple does not allow tor to be run natively on iOS. This means that Firefox cannot be configured to use tor. This leaves the following options for iOS users:
You can use Start9's own Consulate Browser, which is available `here <https://apps.apple.com/us/app/start9-consulate-browser/id1528124570>`_, or you can select another Tor Browser by searching the `App Store <https://www.apple.com/us/search/onion-browser?src=serp>`_.

View File

@@ -1,13 +0,0 @@
.. _firefox-tor-mobile:
**************************************
Setting up Firefox with Tor on Mobile
**************************************
If you are on Android, you can continue after setting up Tor on your device. If you are on iOS, click below for your options.
.. toctree::
:maxdepth: 1
Android<android>
iOS<ios>

View File

@@ -1,84 +0,0 @@
.. _tor-android:
**********************
Running Tor on Android
**********************
Some apps, such as Tor Browser or Cups Messenger, have Tor built in. They do not require additional software or configurations to utilize Tor. Most apps, however, do not have Tor built in. They require an app called Orbot to be installed in order to utilize Tor.
.. youtube:: b__mVfN-BP8
Running Orbot
-------------
Orbot is a system wide proxy for your Android or Graphene device that enables communications over Tor.
1. Download Orbot from the `Play Store <https://play.google.com/store/apps/details?id=org.torproject.android>`_ , or from `F-Droid <https://f-droid.org/packages/org.torproject.android>`_.
2. Launch Orbot.
3. Open the kebab menu in the upper right hand corner and select `Settings`:
.. figure:: /_static/images/tor/orbot_menu.png
:width: 50%
:alt: Orbot menu
4. Make sure the options for `Start Orbot on Boot` and `Allow Background Starts` are checked:
.. figure:: /_static/images/tor/orbot_settings.png
:width: 50%
:alt: Orbot settings
5. Go back, and tap start:
.. figure:: /_static/images/tor/orbot_start.png
:width: 50%
:alt: Orbot start
6. Orbot will start up the Tor service. Once complete, you will see:
.. figure:: /_static/images/tor/orbot_started.png
:width: 50%
:alt: Orbot started
7. That's it. Certain apps, such as Firefox or DuckDuckGo will now just work. Other apps, however, require that Orbot be running VPN mode.
Orbot VPN mode
--------------
To utilize Tor, most apps require that Orbot be running in VPN mode.
1. Disable Private DNS on your device. To do so, navigate to:
``Settings > Network & Internet > Advanced > Private DNS > Off``
.. figure:: /_static/images/tor/private_dns_off.png
:width: 50%
:alt: Private DNS off
Toggle Private DNS to "off"
2. Launch Orbot and toggle VPN Mode on:
.. figure:: /_static/images/tor/orbot_vpn.png
:width: 50%
:alt: Orbot vpn mode
Toggle VPN Mode to "on"
Under `Tor-Enabled Apps`, click the gear icon and add apps you want to utilize Tor.
.. figure:: /_static/images/tor/orbot_apps.png
:width: 50%
:alt: Orbot apps
Examples of applications that need this feature are:
- Bitwarden
- Zap
- Zeus
You can also add the following browsers to the Tor-Enabled Apps list to easily access Tor addresses (`.onion` URLs):
- Chrome
- Brave

View File

@@ -1,18 +0,0 @@
.. _running-tor:
***********
Running Tor
***********
Running Tor on your phone or computer enables apps that are not Tor-enabled to communicate over Tor.
Select your operating system to get started:
.. toctree::
:maxdepth: 1
MacOS<mac>
Windows<windows>
Linux<linux>
Android<android>
iOS<ios>

View File

@@ -1,9 +0,0 @@
.. _tor-ios:
*********************
Setting up Tor on iOS
*********************
Unfortunately, Apple does not allow tor to be run natively on iOS. This leaves 2 options for iOS users:
You can use Start9's own Consulate Browser, which is available `here <https://apps.apple.com/us/app/start9-consulate-browser/id1528124570>`_, or you can select another Tor Browser by searching the `App Store <https://www.apple.com/us/search/onion-browser?src=serp>`_.

Some files were not shown because too many files have changed in this diff Show More