Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-26 10:21:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix up navigation

Browse Source
This commit is contained in:
Lucy Cifferello
2021-12-16 16:49:36 -07:00
parent a7a9f45d36
commit 4c1d6a0e70
163 changed files with 84 additions and 3889 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
site/source/about.rst Normal file
View File

@@ -0,0 +1,4 @@
The Start9 Story
================
TODO

14
site/source/contributing/embassyos.rst
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 />`

24
site/source/dev-docs/dev-faq/faq-contributing.rst Normal file
View File

@@ -0,0 +1,24 @@
.. _faq-contributing:
============
Contributing
============
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.
Do I need to be a professional developer or have coding experience to contribute?
---------------------------------------------------------------------------------
Absolutely not! Contributions can be as simple as finding a typo in our docs, making a suggestion on GitHub, creating educational or promotional content, and the list goes on! Everyone that wants to contribute can do so in some unique way. Please don't hesitate to ***CONTACT LINK*** us for ideas if you're not sure where to begin.
Expound the following into FAQs move to other dev-faq section if necessary:
---------------------------------------------------------------------------
- Release notes need to be in quotations? As it is a string? (they aren’t by default) – this is a yaml thing and SOMETIMES they are required and SOMETIMES NOT
- Ports in manifest – can leave as default (80), as it is a docker container?? - Sure
- Type definitions – is this just for dependencies? Can a blurb be added here for extra clarity?
- Alerts in LND example are not wrapped in quotes, same with CUPS release notes – yaml thing
- Config spec – Admin pass?
- Makefile
- Not required, but simplifies dev process

34
site/source/dev-docs/dev-faq/faq-service-packaging.rst Normal file
View File

@@ -0,0 +1,34 @@
.. _faq-service-packaging:
=====================
Service Packaging FAQ
=====================
Do I need programming experience to package a service for EmbassyOS?
--------------------------------------------------------------------
It would be helpful, but is not a pre-requisite. Linux, dev-ops, and/or systems administration experience would all be helpful as well. Keep in mind that everyone has to start somewhere, and perhaps your journey to development begins with packaging a service for EOS!
What considerations are there when choosing a service for packaging?
--------------------------------------------------------------------
There are several things you will want to consider. Requirements include:
#. Most importantly, pick a service you are passionate about seeing on EmbassyOS
#. Make sure it is :ref:`Open Source <open-source>`
Recommendations that may ease the process:
#. A service that has already been 'dockerized' (has a **working** ``Dockerfile``)
#. A service that incorporates a 'self-hosting' option
#. A service written in a language you are familiar with
#. A service with a strong community
You can check this expansive list if you are in search of ideas: `Awesome Self-Hosted <https://github.com/awesome-selfhosted/awesome-selfhosted>`_
What if I don't need a Config in my service?
--------------------------------------------
Config files can be empty(``{}``), if you do not require config.
How can my service access the data directory of another service?
----------------------------------------------------------------
#. Provider service needs to expose datadir to other services on embassy
#. Consumer services needs to list the provider service as a dependency AND set a particular config value, stating that it wants data from that particular service

13
site/source/dev-docs/dev-faq/index.rst Normal file
View File

@@ -0,0 +1,13 @@
.. _dev-faq:
=============
Developer FAQ
=============
Frequently Asked Questions by and for developers. If you have a suggestion, please use the Github link at the top of the page.
.. toctree::
:hidden:
faq-contributing
faq-service-packaging

19
site/source/dev-docs/index.rst Normal file
View File

@@ -0,0 +1,19 @@
Developer Docs
==============
.. toctree::
:maxdepth: 2
:hidden:
dev-faq/index
service-packaging/index
packaging-example
.. panel-box::
:title: Overview
:id: "dev-docs"
:class: my-panel
* :doc:`Developer FAQ <dev-faq/index>` - Frequently asked questions for developers.
* :doc:`Service Packaging <service-packaging/index>` - Guides on how to package a service for EmbassyOS.
* :doc:`Package Example <packaging-example>` - An example based guide on how to package a service.

510
site/source/dev-docs/packaging-example.rst Normal file
View File

@@ -0,0 +1,510 @@
.. _packaging-example:
=========================
Service Packaging Example
=========================
A rough walkthrough of how to package a service using our example `hello-world-wrapper <https://github.com/Start9Labs/hello-world-wrapper>`_.
Welcome! The following guide will provide the prerequisites, introduce a brief overview of the packaging process, use an example demonstrating how to package a service, and finally describe the submission process. This essentially describes how you can take an existing app (or one you have written yourself), and wrap it up such that it can be added to an EmbassyOS Marketplace!
Pre-requisites
--------------
EmbassyOS (EOS)
...............
It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service.
There are 3 options for this:
#. Build from `source <https://github.com/Start9Labs/embassy-os/build>`_
#. Follow the :ref:`DIY guide <diy>` to build on a Raspberry Pi
#. :ref:`Purchse <purchasing>` a device or copy of the OS
Development Environment
.......................
Once you have EOS installed, you'll want to set up your development system with the necessary software.
At minimum you will need the following:
#. `Docker <https://docs.docker.com/get-docker>`_
#. `Docker-buildx <https://docs.docker.com/buildx/working-with-buildx/>`_
#. ***PLACEHOLDER FOR EOS-SDK***
The following are recommended:
#. `Cargo <https://doc.rust-lang.org/cargo/>`_
#. `yq <https://mikefarah.gitbook.io/yq/>`_ (version 4)
#. `make <https://www.gnu.org/software/make/>`_
#. rust-musl-cross (***PLACEHOLDER FOR NEW MUSL-CROSS REPO***) (For cross compiling Rust to Alpine, not needed otherwise)
Overview
--------
Components
..........
Simply, the package is made up of the following parts:
1. Image - Each service is running in a Docker image. Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
2. Volume - Each service gets a volume, allocated by EOS. The volume directory (for seeding data into the volume) is required: /root/volumes/<service-id>
3. Dependencies - Rules and requirements of your service, which appear as simple UI elements, such as inputs, toggles, and drop-downs. These are enforced by validations and clear user instructions. EmbassyOS has a unique and powerful system for managing dependencies which allows anyone to have the power of systems administrators without the advanced skillset.
4. Manifest - Describes the service and its requirements. This is for the marketplace listing, install considerations, license, donation address, and dependency requirements, and additional info.
5. Config - EOS makes a service's configuration available to the user in the GUI and must be valid regardless of user skill.
6. .s9pk Bundle - The image, config, manifest, and icon files get bundled into a .s9pk package. This is the file a user downloads from the Marketplace, at which point EOS un-packages and installs the service.
Check :ref:`here <service_package_overview>` for a detailed overview of package components.
Service Wrapper Repo and Submodules
...................................
See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository.
Git submodules allow the use of another project while in the working project directory. In this case, you can use an existing app's git repo in order to source its code into your service wrapper.
Simply run:
.. code:: bash
git submodule add <link_to_source_project>
Example - Hello World
---------------------
Okay, let's actually package a service! For this example, we're going to use an example service `Hello World <https://github.com/Start9Labs/hello-world>`_. This repository can also be used as a template to quickly get started with your service. This will give a good overview of service packaging, but obviously your app will be different. This will assume a Linux development environment with all the recommended dependencies listed above. To get started quickly, we'll use Start9's wrapper template.
Clone the Template Repo and Edit the Manifest
.............................................
1. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
.. code-block:: bash
git clone https://github.com/Start9Labs/hello-world-wrapper
cd hello-world-wrapper
2. Edit the ``README.md`` to explain what the service is, what dependencies are required, build/install/contribute instructions, and any other information you'd like.
3. Edit the ``manifest`` file. This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style. You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
Manifest example
................
.. code-block:: yaml
id: hello-world
title: "Hello World"
version: 0.2.0 # Service version
release-notes: "Upgrade to EmbassyOS 2.16.0 and then to v0.3.0"
license: mit
wrapper-repo: "https://github.com/Start9Labs/hello-world-wrapper"
upstream-repo: "https://github.com/Start9Labs/hello-world-wrapper" # There is no upstream repo in this example
support-site: "https://docs.start9.com/"
marketing-site: "https://start9.com/"
build: ["make"] # Series of commands to build into an s9pk, in this case we are using make and all the build commands are in the makefile
min-os-version: "0.3.0" # Minimum required version of EmbassyOS
description:
short: Example service
long: |
Hello World is a simple example of a service wrapper that launches a web interface to say hello and nothing more.
assets:
license: LICENSE # default = LICENSE.md
icon: icon.png # default = icon.png
instructions: docs/instructions.md # default = INSTRUCTIONS.md
docker-images: image.tar # default = image.tar
main:
type: docker
image: main
entrypoint: "/usr/local/bin/docker_entrypoint.sh"
args: []
mounts: {} # Specifies where to put volumes, if there are any. Empty in this example
health-checks: {} # Health check config would go here
config: ~ # Configuration options, none for hello-world, but see below example for format:
# get:
# type: docker
# image: compat
# entrypoint: compat
# args:
# - "config"
# - "get"
# - "/root/.hello-world/start9/config.yaml"
# - "/mnt/assets/config_spec.yaml"
# mounts:
# compat: "/mnt/assets"
# main: "/root"
# io-format: yaml
# set:
# type: docker
# image: compat
# entrypoint: compat
# args:
# - "config"
# - "set"
# - "/root/.hello-world/start9/config.yaml"
# mounts:
# main: "/root"
# io-format: yaml
dependencies: {} # Service pre-requisites, none for hello-world, but see below example (which would make BTC Proxy a dependency) for format:
# btc-rpc-proxy:
# version: ">=0.3.2.1 <0.4.0"
# recommended: true
# critical: false
# optional: Can alternatively configure an external bitcoin node.
# description: Used to fetch validated blocks.
# config:
# check:
# type: docker
# image: compat
# system: true
# # the compat image will contain a tool to check the config rules against the specified dependency
# entrypoint: compat
# args:
# - "dependency"
# - "check"
# - "/mnt/assets/btc-rpc-proxy.rules.yaml"
# mounts:
# compat: "/mnt/assets"
# auto-configure:
# type: docker
# image: compat
# # if true, the denoted image is prebuilt and comes stock with EOS
# # uncommon: if you want something not prebuilt with EOS, you can bundle multiple docker images into the `image.tar` during the `make` build process
# system: true
# entrypoint: compat
# args:
# - "dependency"
# - "auto-configure"
# - "/mnt/assets/btc-rpc-proxy.rules.yaml"
# mounts:
# compat: "/mnt/assets"
volumes: # this is the image where data will go from 0.2.x
main:
type: data # this is the image where files from the project asset directory will go
compat:
type: assets
interfaces:
main:
name: Network Interface
description: Specifies the interface to listen on for HTTP connections.
tor-config:
port-mapping:
80: "80"
lan-config:
80:
ssl: false
mapping: 80
ui: true
protocols:
- tcp
- http
alerts: {}
backup:
create:
type: docker
image: compat # default backup process of the compat docker image is duplicity - EOS will have access to the image defined here
system: true
entrypoint: compat # command to run the backup executable, in this case, duplicity
args: # arguments to pass into the entrypoint, in this case duplicity - in this example, the full command run will be: `duplicity hello-world file:///mnt/backup /root`
- duplicity
- hello-world
- /mnt/backup
- /root
mounts:
# BACKUP is the default volume that is used for backups. This is whatever backup drive is mounted to the defice, or a network filesystem.
# The value here donates where the data mount point will be. Backup drive is mounted to this location, which contains previous backups.
BACKUP: "/mnt/backup"
main: "/root"
restore:
type: docker
image: compat
system: true
entrypoint: compat
args:
- duplicity
- hello-world
- /root
- /mnt/backup
mounts:
# See above comments under `backup: -> mounts:`
BACKUP: "/mnt/backup"
main: "/root"
actions: {} # Commands that can be issued from the UI. None for hello-world, but see below example (resetting a root user) for format:
# reset-root-user:
# name: Reset Root User
# description: Resets your root user (the first user) to username "admin" and a random password; restores any lost admin privileges.
# warning: This will invalidate existing sessions and password managers if you have them set up.
# allowed-statuses:
# - stopped
# implementation:
# type: docker
# image: main
# system: true
# entrypoint: docker_entrypoint.sh
# args: ["reset-root-user"]
# mounts:
# main: "/root"
Note the ``dependencies`` and ``volumes`` sections, which may access another service, e.g. File Browser, such that files stored on a user's Embassy can be accessed in your service.
For details on all the different possible dependency, type, and subtype definitions available for the ``manifest`` file, please see :ref:`here <service_manifest>`.
Edit the Dockerfile and Entrypoint
..................................
Next, it's time to edit the ``Dockerfile``. This defines how to build the image for the package by declaring the environment, building stages, and mounting the package to the volume specified in the ``manifest``.
1. We start by importing a base image, in this case Alpine, as recommended.
.. code:: docker
FROM arm64v8/alpine:3.12
2. Next we issue some commands, which in this example simply updates repositories, installs required software, and finally creates a directory for nginx.
.. code:: docker
RUN apk update
RUN apk add tini
RUN mkdir /run/nginx
3. Next we will add the cross-compiled binary of ``hello-world`` to ``/usr/local/bin/`` and add the ``docker_entrypoint.sh`` file from the repository. Then we set permissions for ``docker_entrypoint.sh``.
.. code:: docker
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
4. Next we set a working directory, expose a port, and set the location of the entrypoint.
.. code:: docker
WORKDIR /root
EXPOSE 80
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
5. Great, let's take a look at our final Embassy Pages ``Dockerfile``:
.. code:: docker
FROM arm64v8/alpine:3.12
RUN apk update
RUN apk add tini
ADD ./hello-world/target/aarch64-unknown-linux-musl/release/hello-world /usr/local/bin/hello-world
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
WORKDIR /root
EXPOSE 80
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"]
6. Okay, let's move on to our ``docker_entrypoint.sh`` file. This is a script that defines what to do when the service starts. It will need to complete any environment setup (such as folder substructure), sets any environment variables, and executes the run command. If you have built a ``configurator``, it will also execute here. Let's take a look at our (extremely basic) Hello World example:
.. code:: bash
#!/bin/sh
export HOST_IP=$(ip -4 route list match 0/0 | awk '{print $3}')
exec tini hello-world
7. We've defined the file, exported the IP address, and run the program.
For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/docker_entrypoint.sh>`_. Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here <https://docs.start9.com/contributing/services/docker.html>`_.
Makefile (Optional)
...................
Here, we will create a ``Makefile``, which is optional, but recommended as it outlines the build and streamlines additional developer contributions. Alternatively, you could use any other build orchestration tool, such as ``nix``, ``bash``, ``python``, ``perl``, ``ruby``, etc instead of ``make``.
Our example ``Makefile`` is agin fairly simple for Hello World. Let's take a look:
.. code-block:: Makefile
ASSETS := $(shell yq e '.assets.[].src' manifest.yaml)
ASSET_PATHS := $(addprefix assets/,$(ASSETS))
VERSION := $(shell toml get hello-world/Cargo.toml package.version)
HELLO_WORLD_SRC := $(shell find ./hello-world/src) hello-world/Cargo.toml hello-world/Cargo.lock
S9PK_PATH=$(shell find . -name hello-world.s9pk -print)
.DELETE_ON_ERROR:
all: verify
verify: hello-world.s9pk $(S9PK_PATH)
embassy-sdk verify $(S9PK_PATH)
# embassy-sdk pack errors come from here, check your manifest, config, instructions, and icon
hello-world.s9pk: manifest.yaml assets/compat/config_spec.yaml config_rules.yaml image.tar docs/instructions.md $(ASSET_PATHS)
embassy-sdk pack
image.tar: Dockerfile docker_entrypoint.sh hello-world/target/aarch64-unknown-linux-musl/release/hello-world
DOCKER_CLI_EXPERIMENTAL=enabled docker buildx build --tag start9/hello-world --platform=linux/arm64 -o type=docker,dest=image.tar .
hello-world/target/aarch64-unknown-linux-musl/release/hello-world: $(HELLO_WORLD_SRC)
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl cargo +beta build --release
docker run --rm -it -v ~/.cargo/registry:/root/.cargo/registry -v "$(shell pwd)"/hello-world:/home/rust/src start9/rust-musl-cross:aarch64-musl musl-strip target/aarch64-unknown-linux-musl/release/hello-world
manifest.yaml: hello-world/Cargo.toml
yq e -i '.version = $(VERSION)' manifest.yaml
1. The first 5 lines set environment variables.
2. The next line simply removes the progress of a ``make`` process if it fails.
.. code-block:: Makefile
.DELETE_ON_ERROR:
1. The ``all`` step is run when the ``make`` command is issued. This attempts the ``verify`` step, which requires that the ``hello-world.s9pk`` must first be built, which first requires the ``image.tar``, and so on. Meaning each step essentially requires the next .
2. So the ``.s9pk`` is created with the ``embassy-sdk pack`` command, supplied with the ``manifest``, ``config_spec``, previously created ``image.tar``, and ``instructions.md``. Your project may likely also contain a ``config_rules`` file. Some of these files we have not yet edited, but that will come shortly.
3. The ``image.tar`` is built below this, the cross-compiled ``hello-world`` source code, and ``manifest`` at the bottom.
For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
Service Config Specification and Rules
......................................
Most self-hosted packages require a configuration. With EmbassyOS, these config options are provided to the user in a friendly GUI, and invalid configs are not permitted. This allows the user to manage their software without a lot of technical skill, and minimal risk of borking their software. Two files are created in this process:
``config_spec.yaml`` for specifying all the config options your package depends on to run
``config_rules.yaml`` for defining the ruleset that defines dependencies between config variables
These are stored in ``assets/compat/`` for 0.2.x compatibility, and in ``/assets/`` for anything built for v0.3.0 and up (almost certainly what you're doing). These files contain a detailed mapping of configuration options with acceptable values, defaults, and relational rule-sets. Hello World has no configuration, as you can see `here <https://github.com/Start9Labs/hello-world-wrapper/blob/0.3.0/assets/compat/config_spec.yaml>`_. Instead, let's take a look at our ``config_spec`` for Embassy Pages, which actually has some config options:
.. code-block:: yaml
homepage:
name: Homepage
description: The page that will be displayed when your Embassy Pages .onion address is visited. Since this page is technically publicly accessible, you can choose to which type of page to display.
type: union
default: welcome
tag:
id: type
name: Type
variant-names:
welcome: Welcome
index: Subdomain Index
filebrowser: Web Page
redirect: Redirect
fuck-off: Fuck Off
variants:
welcome: {}
index: {}
filebrowser:
directory:
type: string
name: Directory Path
description: The path to the directory in File Browser that contains the static files of your website. For example, a value of "websites/resume_site" would tell Embassy Pages to look for that directory in File Browser.
pattern: "^(\\.|[a-zA-Z0-9_ -][a-zA-Z0-9_ .-]*|([a-zA-Z0-9_ .-][a-zA-Z0-9_ -]+\\.*)+)(/[a-zA-Z0-9_ -][a-zA-Z0-9_ .-]*|/([a-zA-Z0-9_ .-][a-zA-Z0-9_ -]+\\.*)+)*/?$"
pattern-description: Must be a valid relative file path
nullable: false
redirect:
target:
type: string
name: Target Subdomain
description: The name of the subdomain to redirect users to. This must be a valid subdomain site within your Embassy Pages.
pattern: '^[a-z-]+$'
pattern-description: May contain only lowercase characters and hyphens.
nullable: false
fuck-off: {}
subdomains:
type: list
name: Subdomains
description: The websites you want to serve.
default: []
range: '[0, *)'
subtype: object
spec:
unique-by: name
display-as: "{{name}}"
spec:
name:
type: string
nullable: false
name: Subdomain name
description: The subdomain of your Embassy Pages .onion address to host the website on. For example, a value of "me" would produce a website hosted at http://me.myaddress.onion.
pattern: "^[a-z-]+$"
pattern-description: "May contain only lowercase characters and hyphens"
settings:
type: union
name: Settings
description: The desired behavior you want to occur when the subdomain is visited. You can either redirect to another subdomain, or load a web page from File Browser.
default: filebrowser
tag:
id: type
name: Type
variant-names:
filebrowser: Web Page
redirect: Redirect
variants:
filebrowser:
directory:
type: string
name: Directory Path
description: The path to the directory in File Browser that contains the static files of your website. For example, a value of "websites/resume_site" would tell Embassy Pages to look for that directory in File Browser.
pattern: "^(\\.|[a-zA-Z0-9_ -][a-zA-Z0-9_ .-]*|([a-zA-Z0-9_ .-][a-zA-Z0-9_ -]+\\.*)+)(/[a-zA-Z0-9_ -][a-zA-Z0-9_ .-]*|/([a-zA-Z0-9_ .-][a-zA-Z0-9_ -]+\\.*)+)*/?$"
pattern-description: Must be a valid relative file path
nullable: false
redirect:
target:
type: string
name: Target Subdomain
description: The subdomain of your Embassy Pages .onion address to redirect to. This should be the name of another subdomain on Embassy Pages. Leave empty to redirect to the homepage.
pattern: '^[a-z-]+$'
pattern-description: May contain only lowercase characters and hyphens.
nullable: false
We essentially have 2 config options (homepage and subdomains), with all of their specifications nested below them. Looking at the homepage, it contains a ``union`` type, which is a necessary dependency, which can be of 5 variants (welcome, index, filebrowser, redirect, or fuck-off). The below images show how this is displayed in the UI.
***IMAGE PLACEHODLER***
***IMAGE PLACEHODLER***
For all the possible types, please check our :ref:`Service Config Spec <service_config>`.
In our example, there is *no need* for a ``config_rules`` file. This is because there is not a rule-set required to define dependencies between config variables. An example of when this would be required would be the following code, from the [LND wrapper](https://github.com/Start9Labs/lnd-wrapper/blob/master/config_rules.yaml):
.. code-block:: yaml
---
- rule: '!(max-chan-size?) OR !(min-chan-size?) OR (#max-chan-size > #min-chan-size)'
description: "Maximum Channel Size must exceed Minimum Channel Size"
Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config.
Properties
..........
Next we need to create the Properties section for our package, to display any relevant info. The result of this step is a ``stats.yaml`` file, which is only populated at runtime. These commands will be issued in the ``docker_entrypoint`` file (or ``configurator``, if you are using one).
***STATS.YAML IS APPARENTLY BEING DEPRECATED, THIS SECTION NEEDS COMMENT***
Instructions
............
Instructions are the basic directions or any particular details that you would like to convey to the user to help get them on their way. Each wrapper repo should contain a ``docs`` directory which can include anything you'd like, but specifically if you include an ``instructions.md`` file, formatted in Markdown language, it will be displayed simply for the user as shown below.
***PLACEHOLDER FOR IMAGE***
You can find the ``instructions.md`` file for Embassy Pages `here <https://github.com/Start9Labs/embassy-pages-wrapper/tree/master/docs>`_ if you are interested.
Backups
.......
Everything in the root folder of the mounted system directory will be stored in an EOS backup. If you want to ignore any particular files for backup, you can create a ``.backupignore`` file and add the relative paths of any directories you would like ignored.
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.
If you are deploying to an alternative marketplace, please shout it out in our community channels!

6
site/source/contributing/services/backups.rst → site/source/dev-docs/service-packaging/backups.rst
View File

@@ -1,8 +1,8 @@
.. _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.
@@ -12,7 +12,7 @@ In this case, create a `.backupignore` file. This file contains a list of relati
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.

16
site/source/contributing/services/config.rst → site/source/dev-docs/service-packaging/config.rst
View File

@@ -1,11 +1,11 @@
.. _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.
@@ -24,10 +24,10 @@ For example, if the user chooses config option A, then config option B must be b
.. _config_spec:
Config Spec
===========
-----------
Overview
--------
........
.. figure:: /_static/images/service/bitcoin_config.png
:width: 80%
@@ -49,7 +49,7 @@ The neat part about this file is that each ValueSpec type gets translated into a
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:
@@ -60,7 +60,7 @@ ConfigSpec Type:
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.
@@ -506,7 +506,7 @@ Example:
.. _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.

10
site/source/contributing/services/docker.rst → site/source/dev-docs/service-packaging/docker.rst
View File

@@ -1,11 +1,11 @@
.. _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>``.
@@ -23,14 +23,14 @@ For instance:
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.

43
site/source/contributing/services/index.rst → site/source/dev-docs/service-packaging/index.rst
View File

@@ -1,12 +1,12 @@
.. _service_pacakge:
.. _service-packaging-spec:
***********************
Service Packaging Guide
***********************
===============================
Service Packaging Specification
===============================
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.
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.
@@ -16,29 +16,20 @@ To start, you will need to acquire EmbassyOS for testing the packaged service. T
- 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.
While you are waiting to receive or assemble a device, you can begin the process of packaging a project. The next sections outline these steps in detail.
Happy building!
.. toctree::
:maxdepth: 1
:hidden:
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 />`
overview
wrapper
manifest
docker
makefile
config
properties
instructions
backups
submission

8
site/source/contributing/services/instructions.rst → site/source/dev-docs/service-packaging/instructions.rst
View File

@@ -1,8 +1,8 @@
.. _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.
@@ -13,11 +13,11 @@ If an ``instructions.md`` file is included, this markdown formatted file will be
: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 />`
:raw-html:`<br />`

6
site/source/contributing/services/makefile.rst → site/source/dev-docs/service-packaging/makefile.rst
View File

@@ -1,8 +1,8 @@
.. _service_makefile:
****************
================
Service Makefile
****************
================
.. note::
@@ -20,7 +20,7 @@ This purpose of this file is to:
- 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.

23
site/source/contributing/services/manifest.rst → site/source/dev-docs/service-packaging/manifest.rst
View File

@@ -1,11 +1,11 @@
.. _service_manifest:
****************
================
Service Manifest
****************
================
Overview
========
--------
This file describes the service and it's requirements. It is used to:
@@ -15,20 +15,21 @@ 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.
For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/blob/master/manifest.yaml#L28>`_ around restoration since data will be overwritten.
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.
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
@@ -84,7 +85,7 @@ Below are the types and sub-type definitions, with necessary elaborations. Any i
.. _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.
@@ -121,7 +122,7 @@ The service ``btc-rpc-proxy`` is a dependency of the service ``c-lightning``. ``
Dependency config rules are processed in order.
Type definitions
----------------
................
Types for ``manifest.yaml`` fields:
@@ -174,7 +175,7 @@ Types for ``manifest.yaml`` fields:
:raw-html:`<br />`
Examples
--------
........
Actual ``manifest.yaml`` files for existing services:
@@ -349,4 +350,4 @@ Cups
.. role:: raw-html(raw)
:format: html
:raw-html:`<br />`
:raw-html:`<br />`

29
site/source/contributing/services/overview.rst → site/source/dev-docs/service-packaging/overview.rst
View File

@@ -1,20 +1,20 @@
.. _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>`_
@@ -31,19 +31,20 @@ Recommended Dependencies
`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.
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 <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>``.
@@ -52,7 +53,7 @@ The volume directory (for seeding data into the volume) is typically: ``/root/vo
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.
@@ -65,7 +66,7 @@ The key to making the system work is a new, domain-specific-language (DSL) and s
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:
@@ -80,21 +81,21 @@ For instance, `LND displays alerts <https://github.com/Start9Labs/lnd-wrapper/bl
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.
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. For a detailed walkthrough of this example, please see the :ref:`Packaging Example<packaging-example>`.
.. role:: raw-html(raw)

6
site/source/contributing/services/properties.rst → site/source/dev-docs/service-packaging/properties.rst
View File

@@ -1,8 +1,8 @@
.. _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.
@@ -15,7 +15,7 @@ The output of this step is a file titled ``stats.yaml``. This file contains a ma
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>`_.

7
site/source/dev-docs/service-packaging/submission.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _submission:
==================
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.

8
site/source/contributing/services/wrapper.rst → site/source/dev-docs/service-packaging/wrapper.rst
View File

@@ -1,8 +1,8 @@
.. _service_wrapper:
***************
===============
Service Wrapper
***************
===============
Each service is bound with a wrapper repository, which contains everything you need to build a service.
@@ -17,7 +17,7 @@ The purpose of this repo is:
- symlink of ``instructions.md`` from ``docs`` directory to wrapper repo root, if included
File Structure
==============
--------------
The project structure should be used as a model:
@@ -35,7 +35,7 @@ The project structure should be used as a model:
└── 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.

9
site/source/getting-started/purchasing.rst
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>`.

49
site/source/knowledge-base/concepts/bitcoin-lightning.rst Normal file
View File

@@ -0,0 +1,49 @@
.. _bitcoin-lightning:
=====================
Bitcoin and Lightning
=====================
.. _bitcoin:
Bitcoin
-------
Bees knees
.. _bitcoin-node:
Bitcoin Node
------------
The Embassy runs a Bitcoin Full Node. When most people say "full node" what they mean (or ought to mean) is "fully validating node", meaning that the node is capable of enforcing the consensus rules of Bitcoin by accepting, validating, and relaying every transaction and block produced by the network. Fully validating nodes are necessary for Bitcoin to exist and function properly and are what protect the network from attackers attempting to bypass the consensus rules. A fully validating node (aka full node) does not need to store the entire blockchain to accomplish this. A node that stores the entire blockchain is called a "full archival node". It is the same as a full node, except that it stores every single valid transaction and block ever produced by the network. There are not many reasons why an individual would want to run a full archival node. Most of the benefits of node operatorship are encompassed by a basic full node described above. Full archival nodes have the added benefit of enabling a block explorer. For instace, if you were interested in looking up the history of a particular address or viewing the details of a transaction, neither of which were your own. If an address or transaction is your own, you can view those details using a pruned node.
All that said, it will soon be possible to run a full archival node with he embassy, should you determine you want block explorer functionality. This will require plugging in an external hard drive to the embassy and changing a setting in the app, and also a resycnhing of the blockchain from genesis.
A video explainin the importance of running a node can be found `here <https://www.youtube.com/watch?v=oX0Yrv-6jVs>`__.
You can learn more about Bitcoin `here <https://lopp.net/bitcoin>`__.
.. _btc-wallets:
Bitcoin Wallets
---------------
The word "wallet" has come to mean a lot of things, depending on who you ask and what software you are using. There are (1) software "wallets", (2) hardware "wallets", (3) seed "wallets", and (4) branch "wallets". The one thing all these wallets have in common is that they have almost nothing in common. As the terms are used today, here is usually what they mean.
(1) SOFTWARE WALLETS - (such as FullyNoded and Specter) Software applications capable of interfacing with hardware wallets (see below), interfacing with one or more nodes, as well as address creation, transaction creation, transaction broadcasting, and transaction display. Most software wallets are also capable of creating and storing public/private keypairs, granting them properties of both hardware wallets (see below) and seed wallets (see below). When we say "wallet", we are referring to software applications that posses a user interface for interacting with the Bitcoin network. If a wallet is capable of creating, storing and using private keys, it should be referred to as just a wallet with signer ability.
(2) HARDWARE WALLETS – (such as ColdCard and Trezor) Physical devices that create and store public/private keypairs, exporting the public keys, NEVER exporting the private keys, and using the private keys to sign transactions on demand. Hardware wallets must interface with a software wallet in order to be useful to a user. For this reason, some have proposed renaming hardware wallets to "hardware signers" for clarity.
(3) SEED WALLETS - Basically just the root of a hierarchical deterministic tree of keypairs. It usually takes the form of a mnemonic phrase of 12 or 24 words. Why people refer to their mnemonic seed as a "wallet" is confusing. Just call it a seed.
(4) BRANCH WALLETS - This is how Specter uses the word wallet, and it is causing a lot of confusion. Whenever you create a new "wallet" in specter, you are actually creating a new hierarchical deterministic branch of your mnemonic seed - or in the case of multisig, multiple seeds. The branch you create can be based on "purpose" (segwit, non-segwit, single-sig, multi-sig, etc), "coin type" (Bitcoin, Doegecoin, etc), or "account" (for personal accounting). Change any of these parameters, and you have yourself a new wallet, which again is just a different branch of the same mnemonic seed that potentially abides by a different set of rules. Perhaps a better name for this concept is "bank". Instead of "wallets", you should be able to create different "banks" from your seed.
.. _lightning-network:
Lightning Network
-----------------
The Lightning Network is a "payment layer" that sits on top of the Bitcoin blockchain, which it uses for final settlement. This allows Bitcoin to scale without affecting the security of the protocol layer. It is easiest to think of Lightning Network as a system that allows anyone to use their Bitcoin to have a running tab (think bar tab) of money they owe each other. For example, 2 friends may have a "channel" (tab) between them that they use for exchanging value. The channel keeps track of who owes what. Those payments can be settled at any time on the Bitcoin blockchain if either or both parties decide to close out. One big incentive to use Lightning is that payments are extremely fast and fees are extremely low. You can find an introductory video explanation `here <https://www.youtube.com/watch?v=rrr_zPmEiME>`__.
You can learn more about Lightning `here <https://lopp.net/lightning>`__.

33
site/source/knowledge-base/concepts/embassy.rst Normal file
View File

@@ -0,0 +1,33 @@
.. _embassy-concepts:
=====================
Embassy and EmbassyOS
=====================
.. _embassy:
Embassy
-------
Embassy is the plug 'n' play hardware device sold by Start9. The current iteration is a Raspberry Pi with an internal speaker in a custom, passively cooled case. The Embassy comes pre-loaded with EmbassyOS.
.. _embassy-os:
EmbassyOS
---------
EmbassyOS (EOS) is a Linux-based operating system custom built for self-hosting open source software. EOS has a range of features that allow anyone to run their own server software without needing all the traditionally required systems administration skills. Advanced dependency management, sensibly defaulted configuration with customization, and minimal reliance on the developers are just a few; all wrapped into a sleek GUI that anyone can operate. No command line required!
.. _product-key:
EmbassyOS Product Key
---------------------
Whether you purchase a device, download an image, or build yourself from source, every copy of EmbassyOS has it's own unique Product Key, which is generated with the creation of each EOS image.
If you purchase a device from us, this is printed on the bottom of your Embassy. If you purchase a download, we provide you the key. If you build from source, the key is created during the build.
The first and foremost use of the Product Key is to encrypt data that is sent to Embassy at :ref:`Initial Setup<initial-setup>`. There are several other usecases. Start9 keeps an anonymous database of all Product Keys that have been purchased by us (ZERO additional data is associated) so that we can verify someone is a "paid user." Currently this is just to allow someone to get a new copy of the EOS image if they have a problem, but in future we intend to give added bonuses to customers who have chosen to pay us for a copy of the software.
.. _services:
Services
--------
The server-side software available on EmbassyOS are referred to as "Services." It's important to distinguish the difference between *services* and *applications*. Applications are generally *client-side*. This means that they are either standalone software, or they reach out to a server in order to operate. Services are *server-side*. These generally run 24/7, waiting for commands from a user via an application.

16
site/source/knowledge-base/concepts/index.rst Normal file
View File

@@ -0,0 +1,16 @@
========
Concepts
========
An overview of the ideas and technologies surrounding Start9 Labs and Embassy
.. toctree::
:maxdepth: 2
open-source
self-hosting
networks
software
bitcoin-lightning
start9
embassy

82
site/source/knowledge-base/concepts/networks.rst Normal file
View File

@@ -0,0 +1,82 @@
.. _networks:
========
Networks
========
.. _lan:
LAN
---
A Local Area Network (LAN) is a computer network that interconnects computers within a limited area such as a residence, school, laboratory, university campus, or office building.
Devices on a LAN are private and protected, such that only devices connected to the same Ethernet or WiFi network can see or communicate with them.
Your Embassy hosts itself on the LAN and is reachable by visiting its ``embassy.local`` URL in the browser while also connected to the LAN.
.. note:: Any device connected to a LAN can inspect all communications on that LAN. To avoid snooping, your Embassy's LAN communications are encrypted using :ref:`ssl`, which requires :ref:`additional setup <ssl-setup>`.
.. _mdns:
MDNS
----
Multicast Domain Name System (MDNS) is a protocol that resolves a human-readable hostname to an IP address on a small network, such as the home or office network you might host your Embassy on.
This is known as a "zeroconf," or zero-configuration service, meaning that you can instantly visit a human-recognizable domain name, such as ``embassy.local`` from your network.
This domain is not broadcast outside of your local network, so it is as private and secure as your LAN.
.. _ssl:
SSL
---
Visiting websites on the Tor network is slow. We wanted to provide a better option to access the Embassy at home. That’s why we created an address for the Embassy that can be accessed on your Local Area Network.
By default, this ``.local`` address is served like a regular website, over HTTP. Browsers make it noticeable when visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn that the connection is not secure.
SSL certificates are what enable websites to move from HTTP to HTTPS, which increases security and makes browsers happy. Using the Secure Sockets Layer protocol, HTTPS enabled websites use certificates to establish authenticated and encrypted links between networked computers. It’s the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two devices, preventing third parties from reading and modifying any personal information transferred. They also verify ownership of a website.
Valid SSL certificates are typically issued and obtained from Certificate Authorities. These trusted third parties generate and distribute certificates, signing them with their trusted private key, which allows the clients who use them to verify their authenticity. Websites obtain a certificate from a CA then load it onto their website’s hosting service or server, allowing the website to load over HTTPS and have all traffic to and from the website be encrypted and secure.
We decided to have the Embassy act as a Certificate Authority. It creates a self-signed certificate, which means that the private key used to sign the digital certificate is the Embassy’s own private key instead of a third party’s.
When you setup SSL for your Embassy and device, the certificate communicates to the client (a browser) that the server (the Embassy) demonstrated ownership of the domain (the ``embassy-xxxxxxxx.local`` address) to the certificate authority (created on the Embassy) at the time of certificate issuance (during the setup process). The Embassy dashboard can then be accessed from a home network (LAN) using a secure HTTPS connection!
For more information on how to setup your devices to enable this feature visit :ref:`ssl-setup`.
.. _tor:
Tor
---
The Onion Router, or Tor, is a free and open source software that enables anonymous communication. By routing Internet traffic though a worldwide, volunteer overlay network of nodes, requests are bundled in layers of encryption like the layers of an onion. The request is relayed across nodes, decrypting a layer only to reveal the next relay destination, until the request meets its final destination, without revealing the source IP address.
If a malicious third party were to intercept a request, they would see a garbled mess of the remaining onion encryption, and would only know that it came from some onion node and was heading to some other onion node. The contents, source, and destination of the message are totally anonymous.
When you use Tor to communicate with services running on the Embassy, all the traffic is onion routed and encrypted, and there are no Tor exit nodes involved - it's totally private with no configuration needed.
Furthermore, every service on the Embassy has a different Tor address, including the device itself. This is for privacy reasons - should one Tor address be exposed, the others will not be compromised. Tor addresses are actually ed25519 keys, which means they also provide all the benefits of cryptographically secure private/public keys.
Here's an introductory video on `Tor <https://www.youtube.com/watch?v=6czcc1gZ7Ak>`__.
.. _tor-browser:
Tor Browser
-----------
The Tor Browser is a version of Firefox specifically made for use with the Tor Network. Tor Browser has Tor built-in, so that you do not need to be running Tor natively in order to use the network. This makes it a great browser for use with your Embassy.
.. caution:: Tor Browser has some advanced security and privacy settings, which can be useful, but please keep in mind that if you raise them from the standard level, you may be unable to use some websites, such as your Embassy UI.
.. _hidden-service:
Tor Hidden Service
------------------
A Tor Hidden Service is essentially just software or a website that is only broadcast on the Tor network. These are identified by a long, random public key, and end with the ``.onion`` suffix. For example, you can visit http://privacy34kn4ez3y3nijweec6w4g54i3g54sdv7r5mr6soma3w4begyd.onion to view the Start9 homepage on Tor.
In order to reach a Hidden Service, you must use a browser that can handle ``.onion`` domains, such as `The Tor Browser <https://www.torproject.org/download/>`_ or by configuring :ref:`Firefox <>` ***REF NEEDED***.

17
site/source/knowledge-base/concepts/open-source.rst Normal file
View File

@@ -0,0 +1,17 @@
.. _open-source:
===========
Open Source
===========
The Internet itself was built on free and publicly available code, with the values of collaboration, peer review, communication, and openness built into its very foundation. This decentralized model evolved into the open source movement, which uses these values to discover new ways to solve problems across boundaries and industries.
Open source software centered around the concept of user freedoms: freedom to see, modify, and redistribute the code to make it work for the user in whatever way they needed. It does not necessarily mean free to use. It means that the software will be better, cheaper, and more flexible if it is freely accessible, openly modifiable, and shared.
If anyone can inspect, modify, and distribute the code, bugs are more rapidly resolved, security vulnerabilities are more quickly audited and exposed. Community driven development efforts enable diverse collaboration which increases project reliability and longevity.
Distinct from open source software is proprietary, or closed source, software. Closed source software is strictly moderated, cannot legally be altered, copied, or distributed, and is paid for to be used as intended without modification. Only the code owners have the right to access the code.
As a company founded on the principles of freedom, every service we support is open source. We believe in contributing to the future of this vibrant and passionate ecosystem.
Open Source ideas explained in `Lego <https://www.youtube.com/watch?v=a8fHgx9mE5U>`_.

12
site/source/knowledge-base/concepts/self-hosting.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _self-hosting:
================
Hosting Software
================
Client-Server Model
-------------------
Self-Hosting
------------

12
site/source/knowledge-base/concepts/software.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _software:
===================
Associated Software
===================
.. _firefox:
Firefox
-------
firefox.com

24
site/source/knowledge-base/concepts/start9.rst Normal file
View File

@@ -0,0 +1,24 @@
.. _start9:
===========
Start9 Labs
===========
Start9 Labs is a small, but rapidly growing team of passionate builders. We are based in Denver, Colorado, but have team members around the world.
.. _start9-origin:
"The Origin of “Start9”
-----------------------
Pokemon is a game for Gameboy. Twitch is a live video streaming app. “Twitch Plays Pokemon” was a popular phenomenon where Twitch users would collaborate to play a SHARED game of Pokemon on Gameboy. Here’s how it worked:
Participants would use the Twitch message board to enter commands that then got executed in the gameplay. For example, if someone entered the command "right”, that would cause the player to move 1 space to the right. Commands would execute immediately after they were received, and anyone could enter a valid command at any time. You can think of Twitch Plays Pokemon as the more practical equivalent of placing a Gameboy in the middle of a crowded room and telling everyone to push buttons at the same time. As you might expect, the gameplay of Twitch Plays Pokemon was quite “twitchy”, but in a very "infinite monkey theory" way, progress could eventually be made.
In an effort to streamline play, a new game mode was devised in which players would “vote” for the next command and, every 4 seconds, whatever command received the most votes over the previous 4 seconds would execute in the game. Also introduced in this mode was the ability to attach multipliers to a command, such that the command would execute that number of times. For example, “right2” would cause the player to move 2 spaces to the right. “right3” would cause the player to move 3 spaces to the right, and so on. The highest number any participant could place after a command was 9, meaning whatever command they entered would execute 9 times. As you might expect, gameplay in this mode was less chaotic, more efficient, but it also meant each participant had less direct and immediate influence over the game. If a group of even 5-10 got together and colluded on their votes, they could practically take over the game and make contrarian ideas irrelevant. The new game mode was called “Democracy”, and the original game mode became known as “Anarchy”. Which game mode was engaged was itself governed by a democratic process: if more participants wanted to play in Democracy mode, then Democracy mode engaged; if more wanted to play in Anarchy mode, then Anarchy mode engaged.
To summarize: in Anarchy mode, everyone had equal influence over the game, but progress was slow and clunky. In Democracy mode, progress was fast and efficient, but colluding groups could marginalize individual participants and ruin the game for them.
So…individual participants discovered a means of effective protest whenever Democracy mode became suffocating, but they could not garner enough votes to switch back to Anarchy mode. Someone would type the command “start9” into the comments. This command meant “open the start menu 9 times in a row”, which, as you might imagine, would be enormously disruptive if executed. The entire screen would be blocked by the start menu, over and over. Typing “start9” was a participant’s way of signaling to other participants that they felt marginalized by Democracy mode, and they were ready to fight back. If others felt the same, they could also begin typing “start9” - then, sure enough, “start9” would finally receive more votes than the colluding group’s command, and the menu opening would begin. Every 4 seconds, the menu would open 9 times…again, and again, and again…until finally, the colluding group would be forced to either cooperate in reverting the game mode back to Anarchy mode or quit altogether.
Playing in Anarchy mode was impractical, but people did not want to play a game where they had no voice, where a group of insiders had taken total control. And so “start9” became the battle cry of the individual, the out-group, a means of signaling to other individuals that it was time to fight back against the usurpers - to use their own rules against them, until there was no alternative but to return control to the individual participants.

8
site/source/support/FAQ/usage-faq.rst → site/source/knowledge-base/faq/faq-basic-use.rst
View File

@@ -1,8 +1,8 @@
.. _usage_faq:
.. _faq-basic-use:
***********
Basic Usage
***********
=============
Basic Use FAQ
=============
Is it easy to use?
------------------

89
site/source/support/FAQ/bitcoin-faq.rst → site/source/knowledge-base/faq/faq-bitcoin.rst
View File

@@ -1,8 +1,8 @@
.. _bitcoin_faq:
.. _faq-bitcoin:
*****************************
Bitcoin and Lightning Network
*****************************
===========
Bitcoin FAQ
===========
Why does the Bitcoin service take so long to be ready?
------------------------------------------------------
@@ -94,83 +94,4 @@ You would use your hardware signer with your wallet, then instruct that wallet t
The reason there is so much confusion about these 3 concepts is that the Bitcoin Core Node comes with its own Wallet (which you should not use), and that wallet is also a signer. In fact, most wallets double as signers, and most wallets do NOT support connecting to your own node. So, most wallets are actually serving as a wallet, a node, and a signer, which might be convenient, but it is neither trustless nor maximally secure. Ideally, you are using a wallet that supports both integrating with a hardware signer (like Coldcard or Trezor) AND a backend node (like on the Embassy).
Please note: of the wallets listed (Specter/Sparrow/Electrum), only Specter is currently able to use Embassy as it's node, but the other two should be available soon.
Why would I want to run a lightning node?
-----------------------------------------
The Lightning Network (LN) is a second 'layer,' built on top of the Bitcoin Protocol. As a result all transactions on LN are backed up by the full security of the Bitcoin network. Lightning is designed for instant payments between nodes, but similar to running a Bitcoin node, running your own is the only way to be sovereign. When you have your own node, you will have the convenience of linking a Lightning wallet, for use on the go. It is also possible to earn an income (granted a very small one at this time), if you are willing to learn how to become a 'routing node.'
How can I get started with Lightning and open my first channel?
---------------------------------------------------------------
You can check out our `"Using Lightning" video <https://www.youtube.com/watch?v=rAvoUNsobws>`_ and learn the basics, including opening a channel with Start9.
.. youtube:: KhU_sTiaN8w
Please remember to always open a "Private" channel with us, or your channel is likely to be closed. Please don't hesitate to reach out to us with any questions.
I opened a Lightning channel, but my local balance is lower than I expected. Where is the remainder?
-----------------------------------------------------------------------------------------------------
A fee to close the channel (onchain) is set aside at opening.
How is that fee estimation calculated?
--------------------------------------
The commitment fees are automatically negotiated every few blocks with your peer. They are on chain txs like all channel closes but they are not broadcast until you attempt to close the channel.
What would happen if I shut down an Embassy that is running a Lightning node with open channels?
------------------------------------------------------------------------------------------------
It is REALLY IMPORTANT to understand that if Lightning services are shut off for long periods of time (days on end) it is possible for your peers to cheat you out of money. If you are not prepared to LOSE ALL THE MONEY IN YOUR CHANNELS, KEEP YOUR NODE RUNNING.
That said, malicious actors on the network right now are probably sparse. However, you are still open to that risk if you do not keep your node online.
Is there a solution to this?
----------------------------
Yes, the concept of a Watchtower was originally conceptualized in the LN whitepaper. A Watchtower is simply a lightning node to which you can give the authority to monitor transactions associated with your open payment channels.
Is it possible to run c-lightning and lnd parallel on the Embassy?
------------------------------------------------------------------
Yes, you may run both. They will operate in their own environments and allow you to run services that depend on either.
How do I connect my Spark mobile app to the Embassy Spark server?
-----------------------------------------------------------------
To use a Spark client, you still need to have Spark installed on the Embassy (which ‘serves’ Spark). Then, under Properties, there is a "Pairing URL". The first part of this is the server URL, and the end portion of it is the access key.
Unfortunately, Spark cannot currently be used in Consulate. This issue is being tracked `here <https://github.com/Start9Labs/consulate-ios/issues/30>`__.
Are my addresses, channels, and balances all stored in LND or in RTL?
---------------------------------------------------------------------
This is all on LND, and RTL is just a GUI for accessing LND. On-chain balance is also part of the LND backup.
How do I find my LND seed so I can write it down to backup?
-----------------------------------------------------------
All LND backups are best done via the Embassy backup flow. It is not supported to use a seed as backup; LND does not expose this. Everything crucial is backed up by our backup system so you do not need your seed. The seed is ONLY for the onchain wallet and does not backup your channel state.
To clarify some of the reasons for this choice:
First off, Lightning is fundamentally different than on-chain/Layer1(L1) bitcoin. There is no way to compress all of that information down into a single 24 word seed in such a way that it will continue to work throughout your usage of the Lightning Network.
So, what is the LND seed *for*? In short, the seed is only used for the Layer1 portion of the funds you have locked up in LND. Due to the live nature of LND and lightning nodes in general, we tend to discourage keeping any significant amounts of money in the onchain portion of your wallet. Given that we cannot actually recover the Layer2(L2) funds with that seed, we needed to have a more holistic way to backup LND funds such that the backup would encompass the ability to get L2 funds back. The Embassy backup system does this, and this approach also happens to be a perfectly valid backup of your L1 funds as well. While Bitcoin users have been trained that the 24 word seed can be used to recover all of their funds, it is important to state that lightning does not and cannot work this way. Exposing the seed gives you two separate things to keep track of in order to recover your funds instead of just one.
Is there a way to use the channel backups made within RTL?
----------------------------------------------------------
The only backup flow we officially support is through the Embassy backup system. This does include the channel backups created automatically by LND, but it must be understood that backups in Lightning are very different than they are on Layer 1 Bitcoin. If you restore from backup all your channels will close, and there is a potential, albeit small, probability for you to lose funds.
When attempting to add new peer, RTL says "server is still in the process of starting," but chain state seems to be fully up to date. What can I do?
-----------------------------------------------------------------------------------------------------------------------------------------------------
Check the LND logs, it can take a while to bootstrap, and starting RTL before this completes could cause errors.
"Server is still in the process of starting," but LND and RTL are running. How can I address this?
---------------------------------------------------------------------------------------------------
You may need to restart the LND Service.
I get the following error from LND: "Error ECONNREFUSED Fetching Info Failed! Unknown Error." What's wrong?
-----------------------------------------------------------------------------------------------------------
LND is waiting for Bitcoin to completely sync, and then needs to catch up on block scanning itself. This may take several minutes, and in some cases might require a restart of the LND service. Do this if the process takes more than 5-10 minutes.
What's the best way to move a small lightning balance?
------------------------------------------------------
It is possible to have lightning balances that are so low that they will not (or barely will) cover the on-chain fees to recoup into an on-chain wallet.
Why are Lightning Network backups and moves so complicated?
-----------------------------------------------------------
There are safe ways to do an “atomic move” of a LN node, but it requires a very specific sequence of actions and certain mistakes can result in your counterparties taking all your funds. Currently, LN works on a punishment scheme. This means if you publish revoked state, the counterparty is entitled to a claim on all the funds in the channel. This incentive system is what makes the whole system work. Without it LN would be subject to various kinds of thievery.
The downside is that backups of old state are not safe. This is because your node might believe it is the real state of the channel, but it may be unaware of states created since then. The problem here is that your node naively believes something different from the truth, which can result in all of the funds being lost. In response to this reality, the safe backup systems, including those generated by RTL, actually do not include channel state. They only list the peers that you had channels with. Restoring these backups essentially politely asks your peers to force close the channels they have with you. In those moments it is possible for your peer to try and cheat you, but they cannot be 100% sure that you can’t punish them, so it’s extremely unlikely that they will attempt to do so.
Please note: of the wallets listed (Specter/Sparrow/Electrum), only Specter is currently able to use Embassy as it's node, but the other two should be available soon.

8
site/source/support/FAQ/embassy-faq.rst → site/source/knowledge-base/faq/faq-embassy.rst
View File

@@ -1,8 +1,8 @@
.. _embassy_faq:
.. _faq-embassy:
*****************************
Embassy (Device, OS, and DIY)
*****************************
===========
Embassy FAQ
===========
Can I run EmbassyOS on a VPS or VM?
-----------------------------------

8
site/source/support/FAQ/general-faq.rst → site/source/knowledge-base/faq/faq-general.rst
View File

@@ -1,8 +1,8 @@
.. _general_faq:
.. _faq-general:
*******
General
*******
===========
General FAQ
===========
What is Start9Labs?
-------------------

84
site/source/knowledge-base/faq/faq-lightning.rst Normal file
View File

@@ -0,0 +1,84 @@
.. _faq-lightning:
=========================
The Lightning Network FAQ
=========================
Why would I want to run a lightning node?
-----------------------------------------
The Lightning Network (LN) is a second 'layer,' built on top of the Bitcoin Protocol. As a result all transactions on LN are backed up by the full security of the Bitcoin network. Lightning is designed for instant payments between nodes, but similar to running a Bitcoin node, running your own is the only way to be sovereign. When you have your own node, you will have the convenience of linking a Lightning wallet, for use on the go. It is also possible to earn an income (granted a very small one at this time), if you are willing to learn how to become a 'routing node.'
How can I get started with Lightning and open my first channel?
---------------------------------------------------------------
You can check out our `"Using Lightning" video <https://www.youtube.com/watch?v=rAvoUNsobws>`_ and learn the basics, including opening a channel with Start9.
.. youtube:: KhU_sTiaN8w
Please remember to always open a "Private" channel with us, or your channel is likely to be closed. Please don't hesitate to reach out to us with any questions.
I opened a Lightning channel, but my local balance is lower than I expected. Where is the remainder?
-----------------------------------------------------------------------------------------------------
A fee to close the channel (onchain) is set aside at opening.
How is that fee estimation calculated?
--------------------------------------
The commitment fees are automatically negotiated every few blocks with your peer. They are on chain txs like all channel closes but they are not broadcast until you attempt to close the channel.
What would happen if I shut down an Embassy that is running a Lightning node with open channels?
------------------------------------------------------------------------------------------------
It is REALLY IMPORTANT to understand that if Lightning services are shut off for long periods of time (days on end) it is possible for your peers to cheat you out of money. If you are not prepared to LOSE ALL THE MONEY IN YOUR CHANNELS, KEEP YOUR NODE RUNNING.
That said, malicious actors on the network right now are probably sparse. However, you are still open to that risk if you do not keep your node online.
Is there a solution to this?
----------------------------
Yes, the concept of a Watchtower was originally conceptualized in the LN whitepaper. A Watchtower is simply a lightning node to which you can give the authority to monitor transactions associated with your open payment channels.
Is it possible to run c-lightning and lnd parallel on the Embassy?
------------------------------------------------------------------
Yes, you may run both. They will operate in their own environments and allow you to run services that depend on either.
How do I connect my Spark mobile app to the Embassy Spark server?
-----------------------------------------------------------------
To use a Spark client, you still need to have Spark installed on the Embassy (which ‘serves’ Spark). Then, under Properties, there is a "Pairing URL". The first part of this is the server URL, and the end portion of it is the access key.
Unfortunately, Spark cannot currently be used in Consulate. This issue is being tracked `here <https://github.com/Start9Labs/consulate-ios/issues/30>`__.
Are my addresses, channels, and balances all stored in LND or in RTL?
---------------------------------------------------------------------
This is all on LND, and RTL is just a GUI for accessing LND. On-chain balance is also part of the LND backup.
How do I find my LND seed so I can write it down to backup?
-----------------------------------------------------------
All LND backups are best done via the Embassy backup flow. It is not supported to use a seed as backup; LND does not expose this. Everything crucial is backed up by our backup system so you do not need your seed. The seed is ONLY for the onchain wallet and does not backup your channel state.
To clarify some of the reasons for this choice:
First off, Lightning is fundamentally different than on-chain/Layer1(L1) bitcoin. There is no way to compress all of that information down into a single 24 word seed in such a way that it will continue to work throughout your usage of the Lightning Network.
So, what is the LND seed *for*? In short, the seed is only used for the Layer1 portion of the funds you have locked up in LND. Due to the live nature of LND and lightning nodes in general, we tend to discourage keeping any significant amounts of money in the onchain portion of your wallet. Given that we cannot actually recover the Layer2(L2) funds with that seed, we needed to have a more holistic way to backup LND funds such that the backup would encompass the ability to get L2 funds back. The Embassy backup system does this, and this approach also happens to be a perfectly valid backup of your L1 funds as well. While Bitcoin users have been trained that the 24 word seed can be used to recover all of their funds, it is important to state that lightning does not and cannot work this way. Exposing the seed gives you two separate things to keep track of in order to recover your funds instead of just one.
Is there a way to use the channel backups made within RTL?
----------------------------------------------------------
The only backup flow we officially support is through the Embassy backup system. This does include the channel backups created automatically by LND, but it must be understood that backups in Lightning are very different than they are on Layer 1 Bitcoin. If you restore from backup all your channels will close, and there is a potential, albeit small, probability for you to lose funds.
When attempting to add new peer, RTL says "server is still in the process of starting," but chain state seems to be fully up to date. What can I do?
-----------------------------------------------------------------------------------------------------------------------------------------------------
Check the LND logs, it can take a while to bootstrap, and starting RTL before this completes could cause errors.
"Server is still in the process of starting," but LND and RTL are running. How can I address this?
---------------------------------------------------------------------------------------------------
You may need to restart the LND Service.
I get the following error from LND: "Error ECONNREFUSED Fetching Info Failed! Unknown Error." What's wrong?
-----------------------------------------------------------------------------------------------------------
LND is waiting for Bitcoin to completely sync, and then needs to catch up on block scanning itself. This may take several minutes, and in some cases might require a restart of the LND service. Do this if the process takes more than 5-10 minutes.
What's the best way to move a small lightning balance?
------------------------------------------------------
It is possible to have lightning balances that are so low that they will not (or barely will) cover the on-chain fees to recoup into an on-chain wallet.
Why are Lightning Network backups and moves so complicated?
-----------------------------------------------------------
There are safe ways to do an “atomic move” of a LN node, but it requires a very specific sequence of actions and certain mistakes can result in your counterparties taking all your funds. Currently, LN works on a punishment scheme. This means if you publish revoked state, the counterparty is entitled to a claim on all the funds in the channel. This incentive system is what makes the whole system work. Without it LN would be subject to various kinds of thievery.
The downside is that backups of old state are not safe. This is because your node might believe it is the real state of the channel, but it may be unaware of states created since then. The problem here is that your node naively believes something different from the truth, which can result in all of the funds being lost. In response to this reality, the safe backup systems, including those generated by RTL, actually do not include channel state. They only list the peers that you had channels with. Restoring these backups essentially politely asks your peers to force close the channels they have with you. In those moments it is possible for your peer to try and cheat you, but they cannot be 100% sure that you can’t punish them, so it’s extremely unlikely that they will attempt to do so.

18
site/source/support/FAQ/services-faq.rst → site/source/knowledge-base/faq/faq-services.rst
View File

@@ -1,8 +1,8 @@
.. _services_faq:
.. _faq-services:
********
Services
********
============
Services FAQ
============
My Embassy is set up, now what?
-------------------------------
@@ -29,11 +29,11 @@ Can the Embassy run 'X' Service??
Potentially. Here is a `comprehensive list <https://github.com/awesome-selfhosted/awesome-selfhosted>`_ of self-hosted services, any of which can theoretically be run on the Embassy.
To get a general idea of what is required of an app, answer these questions:
1. Is it designed to be self-hosted?
2. Can it run on a Raspberry Pi?
3. If it has a P2P interface, does that interface support Tor?
4. Does it ship with it's own web interface? Or is there a Tor-enabled client app?
5. Is there someone willing to put in the time to package it up?
1. Is it designed to be self-hosted?
2. Can it run on a Raspberry Pi?
3. If it has a P2P interface, does that interface support Tor?
4. Does it ship with it's own web interface? Or is there a Tor-enabled client app?
5. Is there someone willing to put in the time to package it up?
If all answers are yes, then it can run on EmbassyOS.

8
site/source/support/FAQ/setup-faq.rst → site/source/knowledge-base/faq/faq-troubleshooting.rst
View File

@@ -1,8 +1,8 @@
.. _setup_faq:
.. _faq-troubleshooting:
*************************
Setup and Troubleshooting
*************************
=============================
Setup and Troubleshooting FAQ
=============================
What do I do first?
-------------------

16
site/source/knowledge-base/faq/index.rst Normal file
View File

@@ -0,0 +1,16 @@
===
FAQ
===
Frequently Asked Questions from Embassy users
.. toctree::
:maxdepth: 2
faq-general
faq-basic-use
faq-troubleshooting
faq-embassy
faq-services
faq-bitcoin
faq-lightning

17
site/source/knowledge-base/index.rst Normal file
View File

@@ -0,0 +1,17 @@
Knowledge Base
==============
.. toctree::
:maxdepth: 2
:hidden:
concepts/index
faq/index
.. panel-box::
:title: Overview
:id: "knowledge-base"
:class: my-panel
* :doc:`Concepts <concepts/index>` - An overview of concepts that will aid in understanding the Start9 Embassy.
* :doc:`FAQ <faq/index>` - The complete guide of frequently asked questions by our users.

29
site/source/misc-guides/available-services.rst
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>`_

19
site/source/misc-guides/tor-firefox/index.rst
View File

@@ -1,19 +0,0 @@
.. _lan-setup:
************
Local Access
************
.. 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
linux
mac
windows
android
ios

13
site/source/misc-guides/tor-firefox/mobile.rst
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>

18
site/source/misc-guides/tor-os/index.rst
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>

9
site/source/misc-guides/tor-os/ios.rst
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>`_.

15
site/source/misc-guides/tor-os/linux.rst
View File

@@ -1,15 +0,0 @@
.. _tor-linux:
********************
Running Tor on Linux
********************
For Debian and Debian-based systems, such as Ubuntu, Mint, etc.
#. Install the Tor proxy service to your system. To do so, open your terminal and run the following command:
.. code-block::
sudo apt update && sudo apt install tor
#. That's it! Your Linux machine is now setup to natively use Tor.

61
site/source/support/FAQ/030-faq.rst
View File

@@ -1,61 +0,0 @@
.. _030_faq:
***********************
EmbassyOS Version 0.3.0
***********************
WHEN will the new version be released?
--------------------------------------
We are as eager to share this major OS overhaul with you as you are to use it. At this time we are in the testing phase. We will update with an ETA as soon as we can.
I have an Embassy already, what do I need to do?
------------------------------------------------
You have 2 options:
1 - Do nothing. Your Embassy will continue to work as it has, however there will likely be no further updates to the 0.2.x series.
2 - Upgrade by adding the `required hardware <https://start9.com/eos-0.3.0>`_ and then install the new version. v0.3.0 will be a free software upgrade to all existing users.
I want to buy an Embassy, what do I need to do?
-----------------------------------------------
Currently we are selling the v0.2.x Embassy. These are shipped immediately and can be upgraded when v0.3.0 is available. We are also selling upgrade kits, which contain all the `required hardware <https://start9.com/eos-0.3.0>`_ for v0.3.0. These will be shipped when the update is complete and will contain a pre-flashed SD card with EmbassyOS v0.3.0. The software update is free.
I want to build an Embassy myself, what do I need to do?
--------------------------------------------------------
You'll simply need to gather the `required hardware <https://start9.com/eos-0.3.0>`_, then wait until the release of v0.3.0, at which time you can purchase the OS, or build from source yourself. New build documentation is forthcoming.
I would like to purchase my own hardware. What factors do I need to consider?
------------------------------------------------------------------------------
1 - Please check the :ref:`DIY guide<diy>` for the necessary Raspberry Pi hardware. ``*`` (Skip this step if you already have an Embassy) ``*``
2 - The most important piece of additional hardware is the external drive. It MUST have a USB 3.x connection (3.0, 3.1, etc are fine). You may use a HDD, an SSD, or an M.2 SSD / NVME. HDDs are cheaper, and the storage capacities can be much higher, however this is at a big performance sacrifice. SSDs are significantly faster (all services and user data will be stored on your external drive), and more generally more reliable than an HDD. This is what we strongly recommend and sell with our official upgrade kits. An M.2 SSD is simply an SSD with a smaller form factor. An NVME SSD is even more performant than an SSD, however that performance will not be accessible due to the USB bottleneck that the data must traverse to the Pi. Drives will range in price radically depending on what you choose.
If you are unsure what drive type is best for you, get an external SSD with a USB 3.0 connection, such as a Samsung T5. These are around $130USD for 1TB and around $240 for 2TB.
3 - For the SD card, any type will work, and 16GB is recommended. A larger card will not offer any benefit. These are $5-10USD. EmbassyOS will be stored on this card.
What size drive do I need?
--------------------------
This will depend on how you want to use your Embassy. We recommend a minimum of 1TB if you intend to run a pruned Bitcoin node, or no Bitcoin node at all, and a 2TB minimum if you intend to run a full archival node, which will add a lot more functionality.
If you intend to run your own "cloud", then consider the amount of data you are storing. If you have lots of video files, for example, you may start filling up the disk fairly quickly. Any service you are currently using should have a simple way for you to view your data usage. Make sure to leave plenty of room for expansion.
Finally, remember that you can always expand to a larger drive in the future. EOS will also be adding additional advanced storage features in the near future.
I want to add an HDD later, in addition to my SSD, what are the performance consequences of doing this?
-------------------------------------------------------------------------------------------------------
At this time, we recommend against this as the Raspberry Pi cannot deliver enough power. We will be revisiting in future, but a powered usb hub would be a minimum requirement for this setup.
Can I use an internal SSD with a USB 3 enclosure? I've heard these may have issues?
------------------------------------------------------------------------------------
Yes, you may, and our original upgrade kits come with this style of drive. We have addressed the known issues in software, and in the rare event of hardware failure, we are here to help.
Does my external drive need its own power supply?
-------------------------------------------------
You may use powered disk drives if you prefer, but if only connecting one SSD, it is not necessary.
Can I re-use the SD Card from my Embassy for the new version?
-------------------------------------------------------------
ONLY if you have no data that you want to transfer. If you have existing files, Lightning channels, etc, then you will need to migrate to the new drive first. Keep in mind that this SD card is major overkill for newer versions of EmbassyOS, which will only require a 16GB SD card. This is because all service and user data will be stored on external drives going forward. You can use the original 128GB card for other purposes, sell it, etc.
``*`` PLEASE FEEL FREE TO REACH OUT TO US WITH ANY QUESTIONS - THIS PROCESS WILL BE STRAIGHTFORWARD AND WE ARE HERE TO HELP :) ``*``

31
site/source/support/FAQ/dev-faq.rst
View File

@@ -1,31 +0,0 @@
.. _dev_faq:
**************************
Contributing & Development
**************************
What versions does this FAQ concern?
------------------------------------
This FAQ concerns only EmbassyOS version 0.3.0 and above. For v0.2.x documentation, please see our :ref:`Service Packaging Guide <service_package_overview>`.
What language does the application I want to package need to be written in?
---------------------------------------------------------------------------
The application can be written in any language, so you may prefer to select an application in a language you are comfortable with (or write your own application). It is only important that the packaging specifications be followed.
What considerations go into selecting an application to package?
----------------------------------------------------------------
With sufficient effort, most any software with the ability to be self-hosted could make its way onto EmbassyOS. That being said, the following features will make service packaging much easier:
- Already built with self-hosting in mind
- Active development / community
- Native proxy/tor support
- Already 'dockerized'
Which possible formats can I use to write the :code:`manifest`, :code:`config_spec`, and :code:`config_rules` files?
--------------------------------------------------------------------------------------------------------------------
JSON, TOML, or YAML are valid options.
I'm getting errors on the `embassy-sdk pack` step. What's going on?
--------------------------------------------------------------------
There is something either missing or incorrect in regard to one of the :code:`manifest`, :code:`configs`, :code:`instructions`, or :code:`icon` files.

17
site/source/support/FAQ/index.rst
View File

@@ -1,17 +0,0 @@
**************************
Frequently Asked Questions
**************************
A collection of common questions and concerns from our community.
.. toctree::
:maxdepth: 2
general-faq
embassy-faq
usage-faq
setup-faq
services-faq
bitcoin-faq
030-faq
dev-faq

124
site/source/support/concepts.rst
View File

@@ -1,124 +0,0 @@
.. _concepts:
Concepts
********
Depending on your background, the Embassy platform may deal with some unfamiliar concepts. While it is not strictly *necessary* for you to understand these concepts to use your Embassy, we know many of you would like to.
.. _start9:
"The Origin of “Start9”
=======================
Pokemon is a game for Gameboy. Twitch is a live video streaming app. “Twitch Plays Pokemon” was a popular phenomenon where Twitch users would collaborate to play a SHARED game of Pokemon on Gameboy. Here’s how it worked:
Participants would use the Twitch message board to enter commands that then got executed in the gameplay. For example, if someone entered the command "right”, that would cause the player to move 1 space to the right. Commands would execute immediately after they were received, and anyone could enter a valid command at any time. You can think of Twitch Plays Pokemon as the more practical equivalent of placing a Gameboy in the middle of a crowded room and telling everyone to push buttons at the same time. As you might expect, the gameplay of Twitch Plays Pokemon was quite “twitchy”, but in a very "infinite monkey theory" way, progress could eventually be made.
In an effort to streamline play, a new game mode was devised in which players would “vote” for the next command and, every 4 seconds, whatever command received the most votes over the previous 4 seconds would execute in the game. Also introduced in this mode was the ability to attach multipliers to a command, such that the command would execute that number of times. For example, “right2” would cause the player to move 2 spaces to the right. “right3” would cause the player to move 3 spaces to the right, and so on. The highest number any participant could place after a command was 9, meaning whatever command they entered would execute 9 times. As you might expect, gameplay in this mode was less chaotic, more efficient, but it also meant each participant had less direct and immediate influence over the game. If a group of even 5-10 got together and colluded on their votes, they could practically take over the game and make contrarian ideas irrelevant. The new game mode was called “Democracy”, and the original game mode became known as “Anarchy”. Which game mode was engaged was itself governed by a democratic process: if more participants wanted to play in Democracy mode, then Democracy mode engaged; if more wanted to play in Anarchy mode, then Anarchy mode engaged.
To summarize: in Anarchy mode, everyone had equal influence over the game, but progress was slow and clunky. In Democracy mode, progress was fast and efficient, but colluding groups could marginalize individual participants and ruin the game for them.
So…individual participants discovered a means of effective protest whenever Democracy mode became suffocating, but they could not garner enough votes to switch back to Anarchy mode. Someone would type the command “start9” into the comments. This command meant “open the start menu 9 times in a row”, which, as you might imagine, would be enormously disruptive if executed. The entire screen would be blocked by the start menu, over and over. Typing “start9” was a participant’s way of signaling to other participants that they felt marginalized by Democracy mode, and they were ready to fight back. If others felt the same, they could also begin typing “start9” - then, sure enough, “start9” would finally receive more votes than the colluding group’s command, and the menu opening would begin. Every 4 seconds, the menu would open 9 times…again, and again, and again…until finally, the colluding group would be forced to either cooperate in reverting the game mode back to Anarchy mode or quit altogether.
Playing in Anarchy mode was impractical, but people did not want to play a game where they had no voice, where a group of insiders had taken total control. And so “start9” became the battle cry of the individual, the out-group, a means of signaling to other individuals that it was time to fight back against the usurpers - to use their own rules against them, until there was no alternative but to return control to the individual participants.
.. _open-source:
Open Source
===========
The Internet itself was built on free and publicly available code, with the values of collaboration, peer review, communication, and openness built into its very foundation. This decentralized model evolved into the open source movement, which uses these values to discover new ways to solve problems across boundaries and industries.
Open source software centered around the concept of user freedoms: freedom to see, modify, and redistribute the code to make it work for the user in whatever way they needed. It does not necessarily mean free to use. It means that the software will be better, cheaper, and more flexible if it is freely accessible, openly modifiable, and shared.
If anyone can inspect, modify, and distribute the code, bugs are more rapidly resolved, security vulnerabilities are more quickly audited and exposed. Community driven development efforts enable diverse collaboration which increases project reliability and longevity.
Distinct from open source software is proprietary, or closed source, software. Closed source software is strictly moderated, cannot legally be altered, copied, or distributed, and is paid for to be used as intended without modification. Only the code owners have the right to access the code.
As a company founded on the principles of freedom, every service we support is open source. We believe in contributing to the future of this vibrant and passionate ecosystem.
Open Source ideas explained in `Lego <https://www.youtube.com/watch?v=a8fHgx9mE5U>`_.
.. _lan:
LAN
===
A Local Area Network (LAN) is a computer network that interconnects computers within a limited area such as a residence, school, laboratory, university campus, or office building.
Devices on a LAN are private and protected, such that only devices connected to the same Ethernet or WiFi network can see or communicate with them.
Your Embassy hosts itself on the LAN and is reachable by visiting its *.local* URL in the browser while also connected to the LAN.
.. note:: Any device connected to a LAN can inspect all communications on that LAN. To avoid snooping, your Embassy's LAN communications are encrypted using :ref:`ssl`, which requires :ref:`additional setup <ssl-setup>`.
.. _ssl:
SSL
===
Visiting websites on the Tor network is slow. We wanted to provide a better option to access the Embassy at home. That’s why we created an address for the Embassy that can be accessed on your Local Area Network.
By default, this `.local` address is served like a regular website, over HTTP. Browsers make it noticeable when visiting a site over HTTP in the URL bar - it could be red, show an unlocked lock, or warn that the connection is not secure.
SSL certificates are what enable websites to move from HTTP to HTTPS, which increases security and makes browsers happy. Using the Secure Sockets Layer protocol, HTTPS enabled websites use certificates to establish authenticated and encrypted links between networked computers. It’s the standard technology for keeping an internet connection secure and safeguarding any sensitive data that is being sent between two devices, preventing third parties from reading and modifying any personal information transferred. They also verify ownership of a website.
Valid SSL certificates are typically issued and obtained from Certificate Authorities. These trusted third parties generate and distribute certificates, signing them with their trusted private key, which allows the clients who use them to verify their authenticity. Websites obtain a certificate from a CA then load it onto their website’s hosting service or server, allowing the website to load over HTTPS and have all traffic to and from the website be encrypted and secure.
We decided to have the Embassy act as a Certificate Authority. It creates a self-signed certificate, which means that the private key used to sign the digital certificate is the Embassy’s own private key instead of a third party’s.
When you setup SSL for your Embassy and device, the certificate communicates to the client (a browser) that the server (the Embassy) demonstrated ownership of the domain (the `start9-xxxxxxxx.local` address) to the certificate authority (created on the Embassy) at the time of certificate issuance (during the setup process). The Embassy dashboard can then be accessed from a home network (LAN) using a secure HTTPS connection!
For more information on how to setup your devices to enable this feature visit :ref:`ssl-setup`.
.. _tor:
Tor
===
The Onion Router, or Tor, is a free and open source software that enables anonymous communication. By routing Internet traffic though a worldwide, volunteer overlay network of nodes, requests are bundled in layers of encryption like the layers of an onion. The request is relayed across nodes, decrypting a layer only to reveal the next relay destination, until the request meets its final destination, without revealing the source IP address.
If a malicious third party were to intercept a request, they would see a garbled mess of the remaining onion encryption, and would only know that it came from some onion node and was heading to some other onion node. The contents, source, and destination of the message are totally anonymous.
When you use Tor to communicate with services running on the Embassy, all the traffic is onion routed and encrypted, and there are no Tor exit nodes involved - it's totally private with no configuration needed.
Furthermore, every service on the Embassy has a different Tor address, including the device itself. This is for privacy reasons - should one Tor address be exposed, the others will not be compromised. Tor addresses are actually ed25519 keys, which means they also provide all the benefits of cryptographically secure private/public keys.
Here's an introductory video on `Tor <https://www.youtube.com/watch?v=6czcc1gZ7Ak>`__.
.. _node:
Bitcoin Full Node
=================
The Embassy runs a Bitcoin Full Node. When most people say "full node" what they mean (or ought to mean) is "fully validating node", meaning that the node is capable of enforcing the consensus rules of Bitcoin by accepting, validating, and relaying every transaction and block produced by the network. Fully validating nodes are necessary for Bitcoin to exist and function properly and are what protect the network from attackers attempting to bypass the consensus rules. A fully validating node (aka full node) does not need to store the entire blockchain to accomplish this. A node that stores the entire blockchain is called a "full archival node". It is the same as a full node, except that it stores every single valid transaction and block ever produced by the network. There are not many reasons why an individual would want to run a full archival node. Most of the benefits of node operatorship are encompassed by a basic full node described above. Full archival nodes have the added benefit of enabling a block explorer. For instace, if you were interested in looking up the history of a particular address or viewing the details of a transaction, neither of which were your own. If an address or transaction is your own, you can view those details using a pruned node.
All that said, it will soon be possible to run a full archival node with he embassy, should you determine you want block explorer functionality. This will require plugging in an external hard drive to the embassy and changing a setting in the app, and also a resycnhing of the blockchain from genesis.
A video explainin the importance of running a node can be found `here <https://www.youtube.com/watch?v=oX0Yrv-6jVs>`__.
You can learn more about Bitcoin `here <https://lopp.net/bitcoin>`__.
Bitcoin wallets
===============
The word "wallet" has come to mean a lot of things, depending on who you ask and what software you are using. There are (1) software "wallets", (2) hardware "wallets", (3) seed "wallets", and (4) branch "wallets". The one thing all these wallets have in common is that they have almost nothing in common. As the terms are used today, here is usually what they mean.
(1) SOFTWARE WALLETS - (such as FullyNoded and Specter) Software applications capable of interfacing with hardware wallets (see below), interfacing with one or more nodes, as well as address creation, transaction creation, transaction broadcasting, and transaction display. Most software wallets are also capable of creating and storing public/private keypairs, granting them properties of both hardware wallets (see below) and seed wallets (see below). When we say "wallet", we are referring to software applications that posses a user interface for interacting with the Bitcoin network. If a wallet is capable of creating, storing and using private keys, it should be referred to as just a wallet with signer ability.
(2) HARDWARE WALLETS – (such as ColdCard and Trezor) Physical devices that create and store public/private keypairs, exporting the public keys, NEVER exporting the private keys, and using the private keys to sign transactions on demand. Hardware wallets must interface with a software wallet in order to be useful to a user. For this reason, some have proposed renaming hardware wallets to "hardware signers" for clarity.
(3) SEED WALLETS - Basically just the root of a hierarchical deterministic tree of keypairs. It usually takes the form of a mnemonic phrase of 12 or 24 words. Why people refer to their mnemonic seed as a "wallet" is confusing. Just call it a seed.
(4) BRANCH WALLETS - This is how Specter uses the word wallet, and it is causing a lot of confusion. Whenever you create a new "wallet" in specter, you are actually creating a new hierarchical deterministic branch of your mnemonic seed - or in the case of multisig, multiple seeds. The branch you create can be based on "purpose" (segwit, non-segwit, single-sig, multi-sig, etc), "coin type" (Bitcoin, Doegecoin, etc), or "account" (for personal accounting). Change any of these parameters, and you have yourself a new wallet, which again is just a different branch of the same mnemonic seed that potentially abides by a different set of rules. Perhaps a better name for this concept is "bank". Instead of "wallets", you should be able to create different "banks" from your seed.
Lightning Network
=================
The Lightning Network is a "payment layer" that sits on top of the Bitcoin blockchain, which it uses for final settlement. This allows Bitcoin to scale without affecting the security of the protocol layer. It is easiest to think of Lightning Network as a system that allows anyone to use their Bitcoin to have a running tab (think bar tab) of money they owe each other. For example, 2 friends may have a "channel" (tab) between them that they use for exchanging value. The channel keeps track of who owes what. Those payments can be settled at any time on the Bitcoin blockchain if either or both parties decide to close out. One big incentive to use Lightning is that payments are extremely fast and fees are extremely low. You can find an introductory video explanation `here <https://www.youtube.com/watch?v=rrr_zPmEiME>`__.
You can learn more about Lightning `here <https://lopp.net/lightning>`__.

11
site/source/support/contact.rst
View File

@@ -1,11 +0,0 @@
.. _contact:
*******
Contact
*******
`Telegram <https://t.me/start9_labs>`_ - best for one off questions or back and forth direct messages
`Matrix <https://matrix.to/#/#community:matrix.start9labs.com>`_ - we will eventually be migrating our community channel off telegram and onto this self hosted communication platform
`support@start9labs.com <mailto:support@start9labs.com>`_ - best for more involved questions

13
site/source/user-manual/general/embassy-config.rst → site/source/user-manual/configuration/basic-config.rst
View File

@@ -1,8 +1,13 @@
**************
Config Options
**************
.. _basic-config:
Click "Config". Here you can set custom configurations for your Embassy. Currently, you can change the "Device Name" and enable/disable "Auto Check for Updates."
===================
Basic Configuration - ***NEEDS UPDATE / SCREENS***
===================
Set Device Name
---------------
Here you can change the name of your Embassy!
.. figure:: /_static/images/embassy_config.png
:width: 90%

14
site/source/user-manual/configuration/index.rst Normal file
View File

@@ -0,0 +1,14 @@
=============
Configuration
=============
Configuration, setup guides, and known limitations are provided here by device
.. toctree::
:maxdepth: 2
basic-config
tor-setup/index
lan-setup/index
wifi
limitations/index

16
site/source/user-manual/configuration/lan-setup/index.rst Normal file
View File

@@ -0,0 +1,16 @@
.. _lan-setup:
============
Local Access
============
When you are on the same network as your Embassy (typically a home or small office), :ref:`Local Access<lan>` is much faster and will allow access to your data, even with no Internet connection.
.. toctree::
:maxdepth: 2
lan-linux
lan-mac
lan-windows
lan-android
lan-ios

12
site/source/user-manual/general/lan-setup/mobile.rst → site/source/user-manual/configuration/lan-setup/lan-ios.rst
View File

@@ -1,14 +1,8 @@
******
Mobile
******
Android
=======
Unfortunately, LAN addresses (URLs ending in `.local`) are not supported on Android devices. This is because Android does not yet natively support mDNS, which is used to access LAN addresses on mobile device browsers. As a result, you cannot access your Embassy's or service's LAN address from the browser on Android. We are tracking this issue `here <https://issuetracker.google.com/issues/140786115>`_, please star it to get more attention from the development team!
.. _lan-ios:
===
iOS
====
===
#. Navigate back to the `Start9 Setup App <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_.

27
site/source/user-manual/configuration/lan-setup/lan-linux.rst Normal file
View File

@@ -0,0 +1,27 @@
.. _lan-linux:
=====
Linux
=====
Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
#. Visit your Embassy at its Tor Address.
#. Navigate to --> Embassy --> Connect Over LAN
.. figure:: /_static/images/embassy_lan_setup.png
:width: 90%
:alt: LAN setup menu item
Select the "Connect over LAN" menu item
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/secure_lan_setup_page.png
:width: 90%
:alt: LAN setup page
Select the "Root Certificate Authority" sub menu
Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

65
site/source/user-manual/configuration/lan-setup/lan-mac.rst Normal file
View File

@@ -0,0 +1,65 @@
.. _lan-mac:
===
Mac
===
#. Visit your Embassy at its Tor Address.
#. Navigate to --> Embassy --> Connect Over LAN
.. figure:: /_static/images/embassy_lan_setup.png
:width: 90%
:alt: LAN setup menu item
Select the "Connect over LAN" menu item
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/secure_lan_setup_page.png
:width: 90%
:alt: LAN setup page
Select the "Root Certificate Authority" sub menu
#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
.. figure:: /_static/images/secure_lan_setup_prompt.png
:width: 90%
:alt: LAN setup prompt
Open with "Keychain Access" and select "OK"
#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
.. figure:: /_static/images/ssl/macos/certificate_untrusted.png
:width: 90%
:alt: Keychain access import menu
Keychain access import menu
#. If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it.
#. Navigate to the "System" tab and find the certificate entitled “Embassy Local Root CA”.
#. Double click on this certificate. A second window will pop up.
#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “when using this certificate”.
.. figure:: /_static/images/ssl/macos/always_trust.png
:width: 90%
:alt: Keychain submenu
Select "Always trust" under SSL dropdown for Embassy Local CA
#. Close this window and enter your password to apply the settings.
#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access.
.. figure:: /_static/images/ssl/macos/certificate_trusted.png
:width: 90%
:alt: Keychain menu trusted certificate
Trusted Embassy Local CA certificate
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

97
site/source/user-manual/general/lan-setup/computer-setup.rst → site/source/user-manual/configuration/lan-setup/lan-windows.rst
View File

@@ -1,73 +1,8 @@
.. _computer-setup:
Computer Setup
==============
MacOS
-----
#. Visit your Embassy at its Tor Address.
#. Navigate to --> Embassy --> Connect Over LAN
.. figure:: /_static/images/embassy_lan_setup.png
:width: 90%
:alt: LAN setup menu item
Select the "Connect over LAN" menu item
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/secure_lan_setup_page.png
:width: 90%
:alt: LAN setup page
Select the "Root Certificate Authority" sub menu
#. Select the option to open your key with Keychain Access. If you choose to save file, double click on it once downloaded.
.. figure:: /_static/images/secure_lan_setup_prompt.png
:width: 90%
:alt: LAN setup prompt
Open with "Keychain Access" and select "OK"
#. Enter your computer password when prompted. It will be imported into your computer’s keychain.
.. figure:: /_static/images/ssl/macos/certificate_untrusted.png
:width: 90%
:alt: Keychain access import menu
Keychain access import menu
#. If the keychain console did not open, press "Command + spacebar" and type “Keychain Access”, and hit enter to open it.
#. Navigate to the "System" tab and find the certificate entitled “Embassy Local Root CA”.
#. Double click on this certificate. A second window will pop up.
#. Open the “Trust” dropdown and select “Always Trust” from the dropdown next to “when using this certificate”.
.. figure:: /_static/images/ssl/macos/always_trust.png
:width: 90%
:alt: Keychain submenu
Select "Always trust" under SSL dropdown for Embassy Local CA
#. Close this window and enter your password to apply the settings.
#. The “Embassy Local Root CA” cert will now read “This certificate is marked as trusted for all users” in Keychain Access.
.. figure:: /_static/images/ssl/macos/certificate_trusted.png
:width: 90%
:alt: Keychain menu trusted certificate
Trusted Embassy Local CA certificate
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
.. _lan-windows:
=======
Windows
-------
=======
#. Install `Bonjour Print Services <https://support.apple.com/kb/DL999>`_ on your Windows machine. This is necessary in order to visit .local addresses on Windows.
#. If you are having issues running Bonjour after installing, you might have had Bonjour previously installed. To fix:
@@ -179,29 +114,3 @@ Windows
#. You can save the settings to the console if desired or cancel.
#. Open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.
Linux
-----
Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.
#. Visit your Embassy at its Tor Address.
#. Navigate to --> Embassy --> Connect Over LAN
.. figure:: /_static/images/embassy_lan_setup.png
:width: 90%
:alt: LAN setup menu item
Select the "Connect over LAN" menu item
#. Select the "Root Certificate Authority" sub menu. This will prompt a download to save the certificate file to your machine.
.. figure:: /_static/images/secure_lan_setup_page.png
:width: 90%
:alt: LAN setup page
Select the "Root Certificate Authority" sub menu
Then open your favorite browser to import this certificate and follow the steps for :ref:`browser setup <browser-setup>`.

16
site/source/user-manual/configuration/limitations/index.rst Normal file
View File

@@ -0,0 +1,16 @@
.. _limitations:
=================
Known Limitations
=================
The following pages describe functionality that is known to be missing from certain platforms. Please bother the appropriate company or developers until they have been remedied.
.. toctree::
:maxdepth: 2
lim-linux
lim-mac
lim-windows
lim-android
lim-ios

13
site/source/user-manual/configuration/limitations/lim-android.rst Normal file
View File

@@ -0,0 +1,13 @@
.. _lim-android:
=========================
Android Known Limitations
=========================
Local Access
------------
Android does not have native support for :ref:`mDNS<mdns>` and therefore cannot resolve ``.local`` addresses. This issue has been long known by Google, and can be tracked `here <https://issuetracker.google.com/issues/140786115>`_ (Google account required to view).
Workarounds
...........
An app developer can add mDNS support, and some projects, such as Chromium, have long `considered it <https://bugs.chromium.org/p/chromium/issues/detail?id=405925>`_, but the real solution is for support to occur at the OS level.

21
site/source/user-manual/configuration/limitations/lim-ios.rst Normal file
View File

@@ -0,0 +1,21 @@
.. _lim-ios:
=====================
iOS Known Limitations
=====================
Tor
---
It is not currently possible to run Tor natively (in the background) on iOS. The best chance for this functionality coming to iOS is via the `iCepa Project <https://github.com/iCepa>`_.
Workarounds
...........
The only way to use Tor on iOS is with apps that come with Tor built-in, such as :ref:`Zap Wallet <zap>`.
Matrix
------
The lack of Tor support on iOS means that Element/Matrix cannot be run on an iPhone in conjunction with your Embassy Matrix server, as that currently requires a Tor connection. This will be fixed if `Element <https://github.com/vector-im/element-ios>` builds Tor into their app.
Workarounds
...........
None currently known.

7
site/source/user-manual/configuration/limitations/lim-linux.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _lim-linux:
=======================
Linux Known Limitations
=======================
Linux has no known limitations in regard to Embassy. Congratulations, Master Race...

7
site/source/user-manual/configuration/limitations/lim-mac.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _lim-mac:
=====================
Mac Known Limitations
=====================
MacOS has no known limitations in regard to Embassy.

5
site/source/user-manual/configuration/limitations/lim-windows.rst Normal file
View File

@@ -0,0 +1,5 @@
.. _lim-windows:
=========================
Windows Known Limitations
=========================

11
site/source/user-manual/configuration/tor-setup/index.rst Normal file
View File

@@ -0,0 +1,11 @@
=========
Tor Setup
=========
Setup :ref:`Tor<tor>` to run on your devices, either natively (in the background), or by configuring an application, such as Firefox.
.. toctree::
:maxdepth: 2
tor-os/index
tor-firefox/index

18
site/source/user-manual/configuration/tor-setup/tor-firefox/index.rst Normal file
View File

@@ -0,0 +1,18 @@
.. _tor-firefox:
====================
Using Tor on Firefox
====================
.. caution:: This guide assumes you are already :ref:`running Tor on your phone or computer<running-tor>`.
Once you have completed native :ref:`Tor Setup<tor-os>`, you can configure :ref:`Firefox<firefox>` to use the Tor Network. This will allow you to visit both ``.onion`` and "normal" (.com, .net, etc) websites from within the same browser.
.. toctree::
:maxdepth: 2
torff-linux
torff-mac
torff-windows
torff-android
torff-ios

9
site/source/misc-guides/tor-firefox/android.rst → site/source/user-manual/configuration/tor-setup/tor-firefox/torff-android.rst
View File

@@ -1,8 +1,8 @@
.. _firefox-tor-android:
.. _torff-android:
**************************************
Setting up Firefox with Tor on Android
**************************************
=======
Android - ***NEEDS UPDATED***
=======
.. 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.
@@ -44,3 +44,4 @@ Once Tor is setup on your system, you can proceed to setup Firefox:
:alt: Firefox whitelist onions screenshot
8. Restart Firefox, and you’re 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.

8
site/source/misc-guides/tor-firefox/ios.rst → site/source/user-manual/configuration/tor-setup/tor-firefox/torff-ios.rst
View File

@@ -1,3 +1,11 @@
.. _torff-ios:
===
iOS -***NEEDS UPDATED***
===
NO TOR FOR YOU
.. _firefox-tor-ios:
**********************************

11
site/source/misc-guides/tor-firefox/desktop.rst → site/source/user-manual/configuration/tor-setup/tor-firefox/torff-linux.rst
View File

@@ -1,8 +1,9 @@
.. _firefox-tor-desktop:
.. _torff-linux:
=====
Linux - ***NEEDS UPDATED***
=====
**************************************
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.
@@ -18,7 +19,7 @@ Setting up Firefox with Tor on Desktop
: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:
Windows:
Click `here <https://registry.start9labs.com/sys/proxy.pac>`_ to get the file and save the file somewhere you won’t delete it. Please remember the location you save the file in if you do not use our example location. For this example:

95
site/source/user-manual/configuration/tor-setup/tor-firefox/torff-mac.rst Normal file
View File

@@ -0,0 +1,95 @@
.. _torff-mac:
===
Mac - ***NEEDS UPDATED***
===
.. 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 won’t 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. You’re 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/>`_.

96
site/source/user-manual/configuration/tor-setup/tor-firefox/torff-windows.rst Normal file
View File

@@ -0,0 +1,96 @@
.. _torff-windows:
=======
Windows - *** NEEDS UPDATED***
=======
.. 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 won’t 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. You’re 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/>`_.

16
site/source/user-manual/configuration/tor-setup/tor-os/index.rst Normal file
View File

@@ -0,0 +1,16 @@
.. _tor-os:
==================
Using Tor Natively
==================
Select your Operating System to setup Tor to run in the background (natively) of any device that you might want to use to access your Embassy with remotely.
.. toctree::
:maxdepth: 2
tor-linux
tor-mac
tor-windows
tor-android
tor-ios

15
site/source/misc-guides/tor-os/android.rst → site/source/user-manual/configuration/tor-setup/tor-os/tor-android.rst
View File

@@ -1,10 +1,10 @@
.. _tor-android:
**********************
Running Tor on Android
**********************
=======
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.
Some apps, such as :ref:`Tor Browser<tor-browser>`, 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 the Tor Network.
.. youtube:: b__mVfN-BP8
@@ -60,7 +60,7 @@ To utilize Tor, most apps require that Orbot be running in VPN mode.
2. Launch Orbot and toggle VPN Mode on:
.. figure:: /_static/images/tor/orbot0.png
.. figure:: /_static/images/tor/orbot_vpn.png
:width: 50%
:alt: Orbot vpn mode
@@ -68,17 +68,16 @@ To utilize Tor, most apps require that Orbot be running in VPN mode.
Under `Tor-Enabled Apps`, click the gear icon and add apps you want to utilize Tor.
.. figure:: /_static/images/tor/orbot1.png
.. figure:: /_static/images/tor/orbot_apps.png
:width: 50%
:alt: Orbot apps
Examples of applications that need this feature are:
- Bitwarden
- Element
- Zeus
You can also add the following browsers to the Tor-Enabled Apps list to easily access Tor addresses (`.onion` URLs):
- Chrome
- Brave
- Firefox

7
site/source/user-manual/configuration/tor-setup/tor-os/tor-ios.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _tor-ios:
===
iOS
===
No Tor for you

25
site/source/user-manual/configuration/tor-setup/tor-os/tor-linux.rst Normal file
View File

@@ -0,0 +1,25 @@
.. _tor-linux:
=====
Linux
=====
Debian / Ubuntu
---------------
For Debian and Debian-based systems, such as Mint, PopOS etc.
Install the Tor proxy service to your system. To do so, open your terminal and run the following command:
.. code-block:: bash
sudo apt update && sudo apt install tor
Arch
----
Simply install Tor with:
.. code-block:: bash
sudo pacman -S tor

6
site/source/misc-guides/tor-os/mac.rst → site/source/user-manual/configuration/tor-setup/tor-os/tor-mac.rst
View File

@@ -1,8 +1,8 @@
.. _tor-mac:
********************
Running Tor on MacOS
********************
===
Mac - ***SIMPLIFY M1 INSTRUCTION***
===
For macOS running on ARM chips (ie. newer macs):
================================================

10
site/source/misc-guides/tor-os/windows.rst → site/source/user-manual/configuration/tor-setup/tor-os/tor-windows.rst
View File

@@ -1,10 +1,10 @@
.. _tor-windows:
**********************
Running Tor on Windows
**********************
=======
Windows
=======
#. First, you need to install the Tor proxy service to your system. Unfortunately, `torproject.org` no longer publishes a standalone Tor binary for Windows, so the recommended way to get it is with the Tor Browser Bundle. You can download it `here <https://www.torproject.org/download/>`_.
#. Unfortunately, `torproject.org` no longer publishes a standalone Tor binary for Windows, so the recommended way to get it is with the Tor Browser Bundle. You can download it `here <https://www.torproject.org/download/>`_.
.. figure:: /_static/images/tor/tor_download_windows.png
:width: 80%
@@ -38,7 +38,7 @@ Running Tor on Windows
sc start tor
.. note:: If you get the error "Access denied," please ensure you are running the command prompt in Administrator mode. You can tell because the prompt will show C:\\Users\\YOUR-USERNAME> if you are NOT in admin mode, and it will show C:\\WINDOWS\\system32 if you ARE in admin mode.
.. tip:: If you get the error "Access denied," please ensure you are running the command prompt in Administrator mode. You can tell because the prompt will show C:\\Users\\YOUR-USERNAME> if you are NOT in admin mode, and it will show C:\\WINDOWS\\system32 if you ARE in admin mode.
.. note:: If you get the error "The specified service already exists," complete the following steps:

12
site/source/user-manual/general/wifi.rst → site/source/user-manual/configuration/wifi.rst
View File

@@ -1,8 +1,10 @@
***************
Setting up WiFi
***************
.. _wifi:
#. Click "WiFi".
===============
Setting up WiFi - ***UPDATE SCREENS***
===============
#. On the Embassy Tab, Under "Settings", Click "WiFi".
#. Click the ``+`` button in the lower right corner.
#. Select the appropriate country.
#. Enter your WiFi SSID and password.
@@ -16,4 +18,4 @@ Setting up WiFi
#. Save
* Clicking *Add* will save the network credentials but not try to connect immediately. This is useful, for example, if you are connected over Ethernet at home and want to add your office WiFi credentials.
* `Add and Connect`.
#. The saved network will appear in the list when successfully added. If you are successfully connected, the WiFi symbol will be green, at which point, you can safely disconnect the Embassy from your router.
#. The saved network will appear in the list when successfully added. If you are successfully connected, the WiFi symbol will be green, at which point, you can safely disconnect the Embassy from your router.

40
site/source/user-manual/connecting.rst
View File

@@ -1,40 +0,0 @@
.. _connecting:
**********
Connecting
**********
With the :ref:`initial-setup` complete, your Embassy is now privately hosted on the Internet and can be accessed right from a web browser. Your Embassy's addresses (its Tor and LAN URLs) are completely private; no one else even knows they exist.
If you accidentally leak your Embassy's addresses, do not worry. You Embassy is also protected by your password; so only you can log in.
Tor
===
Connecting to your Embassy over :ref:`tor` requires using a browser that supports :code:`.onion` URLs.
Currently, Tor is the default and our recommended approach for most users. It *just works*. The one drawback, however, is latency; onion-routed communications over Tor can be slow. For a lightning fast experience, you can connect to your Embassy over LAN (below), but this requires additional setup.
Below are a list of our recommended browsers for Tor:
* `Start9 Consulate <https://apps.apple.com/us/app/consulate/id1528124570>`_ (iOS)
* `Firefox <https://mozilla.org/firefox/new/>`_ (Mac, Windows, Linux)
* `Firefox Beta <https://play.google.com/store/apps/details?id=org.mozilla.firefox_beta>`_ (Android)
* `Tor Browser <https://torproject.org/download/>`_ (Mac, Windows, Linux, Android)
* `Brave <https://brave.com/>`_ (Mac, Windows, Linux)
.. seealso::
:ref:`Setting up Tor for browsers <running-tor>`
:ref:`configure_firefox_tor`
`Announcing the Consulate Browser! <https://medium.com/@start9labs/announcing-the-consulate-browser-76d94a8599cb>`_
LAN
===
Connecting to your Embassy over :ref:`lan` has the benefit of being fast! It requires that your are connected to your home network and using a browser that supports *.local* URLs, which is true for most browsers.
.. seealso:: :ref:`Installing and trusting your Embassy's Root Certificate Authority SSL<ssl-setup>`

9
site/source/user-manual/general/developer-options/index.rst
View File

@@ -1,9 +0,0 @@
*****************
Developer Options
*****************
.. toctree::
:maxdepth: 2
ssh-setup
alt-marketplace

17
site/source/user-manual/general/index.rst
View File

@@ -1,17 +0,0 @@
*******
General
*******
An overview of EmbassyOS general capabilities.
.. toctree::
:maxdepth: 2
embassy-config
updating
wifi
developer-options/index
power
notifications
lan-setup/index
forgot-password

104
site/source/user-manual/general/lan-setup/browser-setup.rst
View File

@@ -1,104 +0,0 @@
.. _browser-setup:
Browser Setup
=============
.. warning:: Make sure you have completed your :ref:`computer setup <computer-setup>` before continuing!
Select the browser you would like to configure to import the certificate from your desktop:
.. .. toctree::
.. :hidden:
.. browser
- :ref:`Brave <brave>`
- :ref:`Chrome <chrome>`
- :ref:`Firefox <firefox>`
- :ref:`Safari <safari>`
.. _brave:
Brave
-----
#. Navigate to your Brave Settings in a new tab.
#. On the left hand sidebar, navigate to *Additional Settings > Privacy and Security*.
#. Add the bottom of the section, select "Manage Certificates".
.. figure:: /_static/images/ssl/browser/brave_security_settings.png
:width: 90%
:alt: Brave privacy and security settings page
#. If you see a trusted “Embassy Local Root CA”, open a new tab to apply the certificate. If this does not work, quit and restart Brave.
#. If you do not see a trusted “Embassy Local Root CA” certificate in the list, ensure the certificate is properly set up on your computer system.
.. figure:: /_static/images/ssl/browser/brave_view_certs.png
:width: 90%
:alt: Brave Manage Certificates sub-menu on MacOS
#. Obtain the LAN address provided in the Setup App and enter it in a new tab.
#. You can now securely navigate to your Embassy over HTTPS!
#. Additionally, you can start a Brave private window with Tor to visit the Tor address over HTTPS (unnecessary in principle, but will circumvent annoying browser warnings).
.. _chrome:
Chrome
------
#. Once you have followed the steps to setup your device, open a new tab to apply the certificate. If this does not work, quit and restart Chrome.
#. Obtain the LAN address provided in the Setup App and enter it in the URL bar.
#. You can now securely navigate to your Embassy over HTTPS!
.. _firefox:
Firefox
-------
#. Navigate to your Firefox Settings in a new tab.
#. Select “Privacy and Security” from the left hand navigation menu.
#. Scroll all the way to the bottom of the page and select “View Certificates”.
.. figure:: /_static/images/ssl/browser/firefox_security_settings.png
:width: 90%
:alt: Firefox security settings
Firefox privacy and security settings page
#. Select the "Authorities" tab from the "Certificate Manager".
#. Click “Import” and open the downloaded *Embassy Local Root CA.crt* file on your device. If you cannot find this, make sure you completed the :ref:`device setup steps <ssl-setup>`.
#. When prompted, check “Trust this CA to identity websites” and select “OK”.
.. figure:: /_static/images/ssl/browser/firefox_security_settings.png
:width: 90%
:alt: Firefox import cert
Firefox import certificate page
#. Ensure the “Embassy Local Root CA” exists under “Start9 Labs”.
#. Click “OK” to save.
#. Open a new tab in Firefox to apply the changes. If this does not work, quit and restart Firefox.
#. Navigate to the LAN address provided in the Setup App.
#. You can now securely navigate to your Embassy over HTTPS!
.. _safari:
Safari
------
Once you have completed the steps to install a SSL certificate on your device, simply open a new tab to apply the changes. If this does not work, quit and restart Safari. You can now securely navigate to the LAN address for your Embassy!

11
site/source/user-manual/general/lan-setup/desktop.rst
View File

@@ -1,11 +0,0 @@
*******
Desktop
*******
Enabling LAN connectivity for desktop involves configuring both your computer and your browser.
.. toctree::
:maxdepth: 1
Computer Setup<computer-setup>
Browser Setup<browser-setup>

15
site/source/user-manual/general/lan-setup/index.rst
View File

@@ -1,15 +0,0 @@
.. _ssl-setup:
*********
LAN Setup
*********
You can securely access your Embassy over LAN while connected to the same network. This method of communicating with your Embassy is significantly faster than Tor, and it also serves as a fallback in case the Tor network is experiencing connectivity issues.
The guides below will walk you through the steps to install and trust your Embassy's SSL certificate, such that your communications are encrypted over HTTPS.
.. toctree::
:maxdepth: 2
Desktop<desktop>
Mobile<mobile>

24
site/source/user-manual/general/notifications.rst
View File

@@ -1,24 +0,0 @@
*************
Notifications
*************
You can view and manage your Notifications inside the "Notifications" tab in the main menu. They include:
* successful or failed EmbassyOS updates
* successful or failed service installations
* successful or failed service backups
* successful or failed service updates
To delete a notification, slide the notification to the left and click the *trash* icon.
.. figure:: /_static/images/embassy_notifications.png
:width: 90%
:alt: Embassy Notifications
All notifications View
.. figure:: /_static/images/embassy_notification.png
:width: 90%
:alt: Embassy notification alert
Example notification alerts

18
site/source/user-manual/general/power.rst
View File

@@ -1,18 +0,0 @@
*****
Power
*****
Restart
=======
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
#. A gentle *bep* will sound when the Embassy is powered back on.
#. A *chime* will sound when the Embassy is ready to use.
Shutdown
========
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
#. It is now safe to unplug the Embassy from power and the ethernet cable, if connected.
.. note:: After a shutdown, the *only* way to turn your Embassy back on is to unplug it and plug it back in. As such, we do not recommend shutting down your Embassy when you are not physically near it. Instead, you should use the restart option.

11
site/source/user-manual/general/updating.rst
View File

@@ -1,11 +0,0 @@
******************
Updating EmbassyOS
******************
#. Navigate to ``Menu > Embassy``
#. Click "Check for Updates"
#. If there is an update available, you will be prompted to install it.
#. While updating, your Embassy will emit a gentle chime every 20 seconds.
#. You can also enable automatic check for updates in the :ref:`Embassy config <auto-update>` tab.
.. note:: Ensure you have a stable Internet connection, and do not unplug your Embassy during an update. Updates usually complete within a few minutes, but depending on the size of the update and your Internet bandwidth, they can sometimes take up to an hour.

17
site/source/user-manual/getting-started/device-guides/dg-android.rst Normal file
View File

@@ -0,0 +1,17 @@
.. _dg-android:
=======
Android
=======
Tor Setup (Connectivity)
------------------------
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-android>`_ to run natively (in the background) on your device. This will allow you to use applications on your Android via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
Tor Firefox Config (Connectivity)
---------------------------------
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-android>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
.. note:: Please see Android's :ref:`Known Limitations<lim-android>` to understand what is currently not possible on these devices

12
site/source/user-manual/getting-started/device-guides/dg-ios.rst Normal file
View File

@@ -0,0 +1,12 @@
.. _dg-ios:
===
iOS
===
LAN Setup (Connectivity, Performance)
-------------------------------------
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-ios>`_ for a fast and secure connection while on your Embassy's local network.
.. note:: Please see iOS's :ref:`Known Limitations<lim-ios>` to understand what is currently not possible on these devices

22
site/source/user-manual/getting-started/device-guides/dg-linux.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _dg-linux:
============
Linux Guides
============
LAN Setup (Connectivity, Performance)
-------------------------------------
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-linux>`_ for a fast and secure connection while on your Embassy's local network.
Tor Setup (Connectivity)
------------------------
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-linux>`_ to run natively (in the background) on your device. This will allow you to use applications on your Linux machine via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
Tor Firefox Config (Connectivity)
---------------------------------
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-linux>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
.. note:: Please see Linux's :ref:`Known Limitations<lim-linux>` to understand what is currently not possible on these devices

22
site/source/user-manual/getting-started/device-guides/dg-mac.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _dg-mac:
===
Mac
===
LAN Setup (Connectivity, Performance)
-------------------------------------
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-mac>`_ for a fast and secure connection while on your Embassy's local network.
Tor Setup (Connectivity)
------------------------
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-mac>`_ to run natively (in the background) on your device. This will allow you to use applications on your Mac via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
Tor Firefox Config (Connectivity)
---------------------------------
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-mac>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
.. note:: Please see Mac's :ref:`Known Limitations<lim-mac>` to understand what is currently not possible on these devices

22
site/source/user-manual/getting-started/device-guides/dg-windows.rst Normal file
View File

@@ -0,0 +1,22 @@
.. _dg-windows:
=======
Windows
=======
LAN Setup (Connectivity, Performance)
-------------------------------------
`Setup LAN Access <docs.start9.com/user-manual/configuration/lan-setup/lan-windows>`_ for a fast and secure connection while on your Embassy's local network.
Tor Setup (Connectivity)
------------------------
`Setup Tor <docs.start9.com/user-manual/configuration/tor-setup/tor-os/tor-windows>`_ to run natively (in the background) on your device. This will allow you to use applications on your Windows machine via the :ref:`Tor Network<tor>` so they can communicate with your Embassy.
Tor Firefox Config (Connectivity)
---------------------------------
`Configure Firefox <docs.start9.com/user-manual/configuration/tor-setup/tor-firefox/torff-windows>`_ to be able to use the :ref:`Tor Network<tor>` so that you can reach ``.onion`` sites without needing to change browsers.
.. note:: Please see Window's :ref:`Known Limitations<lim-windows>` to understand what is currently not possible on these devices

14
site/source/user-manual/getting-started/device-guides/index.rst Normal file
View File

@@ -0,0 +1,14 @@
======================
Device-Specific Guides
======================
An overview of EmbassyOS general capabilities.
.. toctree::
:maxdepth: 2
dg-linux
dg-mac
dg-windows
dg-android
dg-ios

13
site/source/user-manual/getting-started/index.rst Normal file
View File

@@ -0,0 +1,13 @@
===============
Getting Started
===============
Take your first steps!
.. toctree::
:maxdepth: 2
introduction
purchasing
initial-setup
device-guides/index

68
site/source/user-manual/getting-started/initial-setup.rst Normal file
View File

@@ -0,0 +1,68 @@
.. _initial-setup:
=============
Initial Setup - ***NEEDS COMPACTING / SIMPLIFYING***
=============
.. youtube:: DmTlwp5_zvY
Power On
--------
1. Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router.
.. tip:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
2. Plug in your external drive to one of the USB 3.0 (blue) ports on Embassy.
Embassy will initialize, which may take 10-15min. You will hear 2 distinct sounds:
* "bep" ‐ Starting up
* "chime" ‐ Embassy is ready
Setup Your Embassy
------------------
1. Ensure the device you are using (desktop/laptop or mobile) is connected to the same network as your router.
.. caution:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet.
2. Visit ``embassy.local`` from your web browser. You will be prompted to enter your :ref:`Product Key`. This is found on the bottom side of your device.
.. admonition:: Explanation
:class: toggle expand
The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named :ref:`MDNS (or Zeroconf) <mdns>`.
3. Create your *permanent* master password and complete setup.
.. admonition:: Explanation
:class: toggle expand
In this step, the setup process will provide your Embassy with three pieces of critical information:
* An ed25519 private key. Used by the Embassy to create a .onion public address for encrypted and anonymous communication over Tor.
* A 4096 bit RSA private key. Used by the Embassy to create a SSL certificate for encrypted communication over LAN.
* A master password. Used by the Embassy to authenticate you as its owner.
All three secrets are packaged together and transmitted to the Embassy encrypted with its :ref:`Product Key<product-key>`.
.. warning:: There is also currently no way to change your password. Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT. If you lose this password, you may be forced to reset the device, resulting in permanent loss of data. **This one responsibility is the price of sovereignty.**
Enjoy!
------
Your Embassy is now hosted on the private web! After setup is complete you will be presented with connection information. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser, or by accessing it's ``.local`` address from your LAN.
.. admonition:: Troubleshooting
#. Confirm that the Embassy is plugged into both power and Ethernet, with the USB drive in a USB 3.0 (blue) slot.
#. Confirm the Embassy emitted two sounds when powering on: a bep and a chime.
#. Confirm you are entering the product key correctly and exactly.
#. Confirm your device you are using is not connected to a "Guest" network
#. Confirm your device is not using a VPN.
#. Try to refresh the ``embassy.local`` page.
#. Very rarely, a router may not support mDNS. In this case:
* On your desktop or laptop computer, navigate to your router configuration settings within the browser. This is usually an IP address such as 192.168.1.1. A simple web search will usually reveal how to access the router configuration settings for a particular brand.
* Once in the router config settings, find the section that lists the devices on your network. You should see an item labeled "embassy". Take note of the associated IP address and enter it into your browser's URL field to enter the setup.

10
site/source/getting-started/introduction.rst → site/source/user-manual/getting-started/introduction.rst
View File

@@ -1,15 +1,15 @@
.. _introduction:
************
============
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.
:ref:`Embassy<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.
Every communication between you and your Embassy is end-to-end encrypted and onion routed over the :ref:`Tor network<tor>`. 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>`.
To get an Embassy, you can :ref:`purchase<purchasing>` one directly from :ref:`Start9<start9>`, or you can :ref:`build one yourself<diy>`.

9
site/source/user-manual/getting-started/purchasing.rst Normal file
View File

@@ -0,0 +1,9 @@
.. _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 :ref:`EmbassyOS<embassy-os>`. 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, as well as Lightning payments.
If you prefer to build your own Embassy, you can follow the :ref:`DIY Guide <diy>`.

26
site/source/user-manual/index.rst
View File

@@ -1,21 +1,27 @@
User Manual
============
=============
.. toctree::
:maxdepth: 2
:hidden:
general/index
managing-services/index
connecting
initial-setup
getting-started/index
configuration/index
troubleshooting/index
tuning/index
walkthrough/index
services/index
.. panel-box::
:title: Overview
:id: "user-manual"
:id: "getting-started"
:class: my-panel
* :doc:`Initial Setup <initial-setup>` - How to setup your Embassy
* :doc:`Connecting <connecting>` - Ways to connect to your Embassy
* :doc:`Managing Services <managing-services/index>` - Working with the open source projects made compatible for the Embassy
* :doc:`General <general/index>` - An overview of EmbassyOS general capabilities
EmbassyOS is designed to work out of the box with a minimal setup and immediate practicality. That being said, there are a great many different use-cases and utilities that can be added at your convenience. You can get started right away with :ref:`Initial Setup <initial-setup>`. In the `User Manual <link>`, you will find information on what EmbassyOS can do for you, as well as configuration and customization options. Use our `Knowledgebase <link>` to learn more about the technologies behind Embassy, including Frequently Asked Questions. When you're ready to build, please check out our `Developer Docs <link>`. Please don't hestitate to `Contact Us <https://start9.com/contact>`_ if you have any issues, questions, or suggestions that are not covered here.
* :doc:`Getting Started <getting-started/index>` - Get started with understanding your Embassy device.
* :doc:`Configuration Options <configuration/index>` - Configuration options for EmbassyOS.
* :doc:`Troubleshooting <troubleshooting/index>` - Help to resolve common issues.
* :doc:`Tuning <tuning/index>` - Customize with advanced configurations.
* :doc:`Services <services/index>` - Overview of services available on EmbassyOS.
* :doc:`Walkthrough <walkthrough/index>` - Overview of Embassy capabilities.

81
site/source/user-manual/initial-setup.rst
View File

@@ -1,81 +0,0 @@
.. _initial-setup:
*************
Initial Setup
*************
.. youtube:: DmTlwp5_zvY
Download the Setup App
======================
`App Store <https://apps.apple.com/us/app/start9-setup-app/id1528125889>`_
`Google Play <https://play.google.com/store/apps/details?id=com.start9labs.setup>`_
`APK direct download <https://github.com/Start9Labs/setup-app/releases>`_
Power On
========
Connect your Embassy to power and Internet, normally using an ethernet port on your home Internet router.
.. note:: To avoid networking issues, it is recommended to use your primary router, not an extender or mesh router.
You will hear 2 distinct sounds:
* "bep" ‐ Powering on
* "chime" ‐ Embassy is ready
Claim Your Embassy
==================
1. Ensure your phone is connected to the same WiFi network as your router.
.. warning:: Sometmies a router will have a "guest WiFi network," which might be different than the network your Embassy is placed on via ethernet.
2. Inside the Setup App, enter the product key located on the bottom of your Embassy
.. admonition:: Explanation
:class: toggle expand
The product key is used to discover your Embassy's IP address on the Local Area Network using a hashing function and a protocol named MDNS (or Zeroconf). Once in possession of the Embassy's local IP address, the Setup App can now communicate directly with the Embassy.
.. admonition:: Troubleshooting
:class: toggle expand
#. Confirm that the Embassy is plugged into both power and Ethernet.
#. Confirm the Embassy emitted two sounds when powering on: a bep and a chime.
#. Confirm you are entering the correct product key.
#. Confirm your phone is not connected to a "Guest" network
#. Confirm your phone is not using a VPN.
#. Close and reopen the Setup App and try again.
#. Rarely, certain routers do not support mDNS. Please see the "Advanced" tab.
.. admonition:: Advanced
:class: toggle expand
If your router does not support mDNS
* On your desktop or laptop computer, navigate to your router configuration settings within the browser. This is usually an IP address such as 192.168.1.1. A simple Google search will usually reveal how to access the router configuration settings for a particular brand.
* Once in the router config settings, find the section that lists the devices on your network. You should see an item labeled "start9labs". Take note of the associated IP address and enter it into the Setup App in the "LAN IP Address" input field.
3. Create your *permanent* master password and complete setup.
.. admonition:: Explanation
:class: toggle expand
In this step, the Setup App will provide your Embassy with three pieces of critical information:
* A ed25519 private key. Used by the Embassy to create a .onion public address for encrypted and anonymous communication over Tor.
* A 4096 bit RSA private key. Used by the Embassy to create a SSL certificate for encrypted communication over LAN.
* A master password. Used by the Embassy to authenticate you as its owner.
All three secrets are packaged together and transmitted to the Embassy encrypted with its product key.
.. warning:: There is also currently no way to change your password. Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT. If you lose this password, you may be forced to reset the device, resulting in permanent loss of data.
Setup Complete!
===============
Your Embassy is now hosted on the private web. You can view and manage your Embassy by visiting its unique Tor Address from any Tor-enabled browser. The Setup App contains our recommendations for various devices.

105
site/source/user-manual/managing-services/backups.rst
View File

@@ -1,105 +0,0 @@
*******
Backups
*******
Creating frequent service backups is critical. If anything happens to your Embassy, these backups are your only path to recovering your data.
.. warning:: Backups are encrypted using your Embassy master password. If you forget your password, you lose your backups.
Creating A Backup
=================
To begin the backup process:
1. Enter a USB drive with sufficient capacity into a USB port on the device. The blue ports are USB 3.0. The black ports are USB 2.0.
2. Navigate to the `Services` sub menu from the main dashboard menu.
3. Select the service to be backed-up.
4. Select the floppy disc icon next to the `Last Backup` menu item. If a backup was never completed, this should say "never".
.. figure:: /_static/images/bitcoin_view.png
:width: 90%
:alt: Bitcoin Core Service Sub Menu
Bitcoin Core Service Sub Menu
5. In the modal prompt, select the available disc space. If no option is marked as available, ensure the USB drive has enough space and that it is properly inserted.
.. figure:: /_static/images/bitcoin_backup_view_storage.png
:width: 90%
:alt: Bitcoin Core Service Backup Storage
Backup menu with available storage space
.. figure:: /_static/images/bitcoin_backup_view_no_storage.png
:width: 90%
:alt: Bitcoin Core Service Backup No Storage
Backup menu with no available storage disc
6. Enter the master password to encrypt the backup.
7. "Creating Backup..." will appear on the service sub menu while the backup is in process.
.. figure:: /_static/images/bitcoin_creating_backup.png
:width: 90%
:alt: Bitcoin Core Service Backup No Storage
Creating Backup
8. A notification will emit when the backup has successfully completed.
9. The `Last Backup` menu item in the service will now indicate the date and time at which the last backup was made.
Restoring A Backup
==================
To begin the backup restore process:
1. Enter the same USB stick used to originally backup the service.
2. Navigate to the `Services` sub menu from the main dashboard menu.
3. Select the service to be backed-up.
4. Select the `Restore from backup` menu item.
.. figure:: /_static/images/restore_backup_menu.png
:width: 90%
:alt: Restore backup from Services tab
Restore backup from Services tab
5. In the modal prompt, select the same disc used to originally back up the service. If no option is marked as available, ensure the USB drive is properly inserted.
.. figure:: /_static/images/restore_backup_submenu.png
:width: 90%
:alt: Restore backup submenu
Restore backup sub-menu options
6. Note the warning that restoring will wipe current data.
.. figure:: /_static/images/backup_warning.png
:width: 90%
:alt: Backup warning message
Backup warning message
7. Enter the master password to decrypt the backup and select `Restore`.
.. figure:: /_static/images/decrypt_backup.png
:width: 90%
:alt: Decrypt backup
Decrypt backup view
8. "Restoring Backup..." will appear on the service sub menu while the restoration is in process.
.. note::
The service might be momentarily unreachable as it starts back up. This is expected behavior.
.. figure:: /_static/images/restoring_backup.png
:width: 90%
:alt: Restoring backup
Restoring backup view
9. A notification will emit when the backup restoration has successfully completed.

20
site/source/user-manual/managing-services/index.rst
View File

@@ -1,20 +0,0 @@
.. _managing-services:
*****************
Managing Services
*****************
Services are self-hosted, open source projects made compatible for EmbassyOS. Each service has been independently developed by members of the open source community. The Embassy enables configuration, customization and a one click install.
.. note:: Some services require configuration before starting up. You can only connect to and use a service once it is in a *running* state.
.. toctree::
:maxdepth: 2
installing
instructions
backups
service-config
properties
logs
managing-deps

30
site/source/user-manual/managing-services/installing.rst
View File

@@ -1,30 +0,0 @@
*******************
Install / Uninstall
*******************
.. note:: Some services have :ref:`dependencies<managing-dependencies>` on other services. Adding, updating, or removing a service can sometimes have requirements or consequences for other services. Your Embassy will inform you of these issues along the way.
Installing
==========
To add a new service, find it's listing inside the Service Marketplace: *Marketplace > [Service Name] > Install*.
Depending on the size of the service and your Internet connection, installation should take between 60 seconds and a few minutes.
After installation, you can view the service's instructions by navigating to *Services > [Service Name] > Instructions*
.. note:: You can only start and use a service once its dependencies are met, its :ref:`configuration<service-config>` complete, and is in a *running* state.
Updating
========
To see if an update is available for a service, you can click the *refresh* button inside the dashboard of the installed service or by visiting its listing in the Service Marketplace.
If an update is available, simply click "Update" and confirm the action.
Uninstalling
============
To remove a service, navigate to *Services > [Service Name] > Uninstall*.

19
site/source/user-manual/managing-services/instructions.rst
View File

@@ -1,19 +0,0 @@
************
Instructions
************
To view the instructions for a particular service, navigate to *Services > [Service Name] > Instructions*.
.. figure:: /_static/images/bitcoin_instructions.png
:width: 90%
:alt: Bitcoin instructions menu item
Instructions menu item
.. figure:: /_static/images/bitcoin_instructions_view.png
:width: 90%
:alt: Bitcoin instructions view
Instructions view
.. note:: For advanced instructions and integration guides, visit the wrapper repository for an :ref:`available service <available-services>`.

7
site/source/user-manual/managing-services/logs.rst
View File

@@ -1,7 +0,0 @@
************
Viewing Logs
************
Naviage to *Services > [Service Name] > Logs*
Every service emits logs while it is in a *running* state. Logs give an *under-the-hood* glimpse of a service and can be extremely useful for debugging purposes. To a non-technical user, logs may look like gibberish, and sometimes there is nothing to see at all.

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