mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 18:31:53 +00:00
SDK, dev docs images, SSH-over-Tor, Misc edits
This commit is contained in:
kn0wmad
BIN
site/source/_static/images/dev/instructions.svg
Normal file
BIN
site/source/_static/images/dev/instructions.svg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 276 KiB |
BIN
site/source/_static/images/dev/pages0.svg
Normal file
BIN
site/source/_static/images/dev/pages0.svg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 124 KiB |
BIN
site/source/_static/images/dev/pages1.svg
Normal file
BIN
site/source/_static/images/dev/pages1.svg
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 134 KiB |
@@ -6,47 +6,37 @@ Embassy-SDK
|
||||
|
||||
.. warning:: This is for developers only!! Anything you do while SSH'd into your Embassy is NOT SUPPORTED, unless under the guidance of a Start9 technician.
|
||||
|
||||
.. When interacting with Embassy directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control EmbassyOS in many of the same ways that the UI can, but with finer controls and deeper insights.
|
||||
You can install to your system by running the following from you ``embassy-os`` directory:
|
||||
|
||||
.. In order to use Embassy-CLI, you will first need to authorize yourself with the following command...
|
||||
.. code-block:: bash
|
||||
|
||||
.. .. code-block:: bash
|
||||
|
||||
.. embassy-cli auth login
|
||||
|
||||
.. and enter your Embassy Master Password at the prompt.
|
||||
cargo install --bin=embassy-sdk --path=. --no-default-features --verbose
|
||||
|
||||
|
||||
.. You can enter ``embassy-cli help`` or ``embassy-cli <option> help`` to get an overview of capabilities:
|
||||
You can enter ``embassy-sdk help`` or ``embassy-sdk <option> help`` to get an overview of capabilities:
|
||||
|
||||
.. .. code-block:: bash
|
||||
.. code-block:: bash
|
||||
|
||||
.. Embassy CLI
|
||||
embassy-sdk --help
|
||||
Embassy SDK
|
||||
|
||||
.. USAGE:
|
||||
.. embassy-cli [OPTIONS] <SUBCOMMAND>
|
||||
USAGE:
|
||||
embassy-sdk [OPTIONS] <SUBCOMMAND>
|
||||
|
||||
.. FLAGS:
|
||||
.. --help Prints help information
|
||||
.. -V, --version Prints version information
|
||||
FLAGS:
|
||||
-h, --help Prints help information
|
||||
-V, --version Prints version information
|
||||
|
||||
.. OPTIONS:
|
||||
.. -c, --config <config>
|
||||
.. -h, --host <host>
|
||||
.. -p, --proxy <proxy>
|
||||
OPTIONS:
|
||||
-c, --config <config>
|
||||
|
||||
.. SUBCOMMANDS:
|
||||
.. auth Login/logout and manage sessions
|
||||
.. backup Manage backups
|
||||
.. db Interact with the Database
|
||||
.. disk Information on the external drive
|
||||
.. echo Echoes
|
||||
.. git-info Print the current git hash
|
||||
.. help Prints this message or the help of the given subcommand(s)
|
||||
.. inspect Details on services and their components
|
||||
.. net Network information
|
||||
.. notification Control UI notifications
|
||||
.. package Interact with packages
|
||||
.. server EmbassyOS operations and information
|
||||
.. ssh Manage SSH keys
|
||||
.. wifi Manage WiFi networks
|
||||
SUBCOMMANDS:
|
||||
git-info Print current git hash
|
||||
help Prints this message or the help of the given subcommand(s)
|
||||
init Initialize
|
||||
inspect Inspect a .s9pk
|
||||
pack Package a service into the .s9pk format
|
||||
verify Verify a .s9pk is valid
|
||||
|
||||
|
||||
Please visit https://github.com/Start9Labs/embassy-os/tree/master/backend for more details
|
||||
|
||||
@@ -8,17 +8,17 @@ Developer Docs
|
||||
:maxdepth: 3
|
||||
:hidden:
|
||||
|
||||
dev-faq/index
|
||||
dev-tools/index
|
||||
packaging-example
|
||||
service-packaging/index
|
||||
dev-faq/index
|
||||
|
||||
.. panel-box::
|
||||
:title: Overview
|
||||
:id: "dev-docs"
|
||||
:class: my-panel
|
||||
|
||||
* :doc:`Developer FAQ <dev-faq/index>` - Frequently asked questions by developers in regard to EmbassyOS and packaging services.
|
||||
* :doc:`Developer Tools <dev-tools/index>` - An overview of tools for those interested in contributing to the OS or packaging a service.
|
||||
* :doc:`Service Packaging <service-packaging/index>` - The full specification for packaging a service.
|
||||
* :doc:`Package Example <packaging-example>` - A walkthrough of how to package a service using an example.
|
||||
* :doc:`Service Packaging <service-packaging/index>` - The full specification for packaging a service.
|
||||
* :doc:`Developer FAQ <dev-faq/index>` - Frequently asked questions by developers in regard to EmbassyOS and packaging services.
|
||||
|
||||
@@ -4,6 +4,10 @@
|
||||
Service Packaging Example
|
||||
=========================
|
||||
|
||||
.. contents::
|
||||
:depth: 4
|
||||
:local:
|
||||
|
||||
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 into an ``s9pk`` such that it can be added to an EmbassyOS (EOS) Marketplace! The ``s9pk`` is the final product, which is the portable version of a package that is understood by EOS, and can be distributed to any EOS users either directly, or via a Marketplace.
|
||||
@@ -29,13 +33,13 @@ Once you have EOS installed, you'll want to set up your development system set u
|
||||
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***
|
||||
#. `Embassy-SDK <https://github.com/Start9Labs/embassy-os/tree/master/backend>`_
|
||||
|
||||
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)
|
||||
#. `rust-musl-cross <https://github.com/Start9Labs/rust-musl-cross>`_ (For cross compiling Rust to Alpine, not needed otherwise)
|
||||
|
||||
Overview
|
||||
--------
|
||||
@@ -69,7 +73,7 @@ Simply run:
|
||||
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. The guide will provide good overview of service packaging, but obviously your app will be different, so don't hesitate to reach out to our community `dev chat <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ with questions.
|
||||
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. The guide will provide good overview of service packaging, but obviously your app will be different, so don't hesitate to reach out to our community `dev chat <https://matrix.to/#/#community-dev:matrix.start9labs.com>`_ with questions.
|
||||
|
||||
The commands below assume a Linux development environment with all the recommended dependencies listed above installed. To get started quickly, we'll use Start9's wrapper template.
|
||||
|
||||
@@ -276,7 +280,7 @@ Next, it's time to edit the ``Dockerfile``. This defines how to build the image
|
||||
ADD ./docker_entrypoint.sh /usr/local/bin/docker_entrypoint.sh
|
||||
RUN chmod a+x /usr/local/bin/docker_entrypoint.sh
|
||||
|
||||
1. Next, we set a working directory, and set the location of the entrypoint. Exposing ports is not necessary for EOS, but its often useful to leave this line for clarity.
|
||||
1. Next, we set a working directory, and set the location of the entrypoint. Exposing ports is not necessary for EOS, but its often useful to leave this line for clarity.
|
||||
|
||||
.. code:: docker
|
||||
|
||||
@@ -366,7 +370,7 @@ Our example ``Makefile`` is again fairly simple for Hello World. Let's take a l
|
||||
|
||||
.DELETE_ON_ERROR:
|
||||
|
||||
3. 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. In this case, each step requires the next and each step indicates the necessary existence of a file. If an indicated file has been altered, such as the `docker_entrypoint.sh`, then any step that contains this file will be rebuilt.
|
||||
3. 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. In this case, each step requires the next and each step indicates the necessary existence of a file. If an indicated file has been altered, such as the `docker_entrypoint.sh`, then any step that contains this file will be rebuilt.
|
||||
|
||||
4. 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.
|
||||
|
||||
@@ -473,9 +477,13 @@ These are stored in ``assets/compat/`` for 0.2.x compatibility, and in ``/assets
|
||||
|
||||
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***
|
||||
.. figure:: /_static/images/dev/pages0.svg
|
||||
:width: 60%
|
||||
:alt: Pages Config
|
||||
|
||||
***IMAGE PLACEHODLER***
|
||||
.. figure:: /_static/images/dev/pages1.svg
|
||||
:width: 60%
|
||||
:alt: Pages Union
|
||||
|
||||
For all the possible types, please check our :ref:`Service Config Spec <service_config>`.
|
||||
|
||||
@@ -501,7 +509,9 @@ 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***
|
||||
.. figure:: /_static/images/dev/instructions.svg
|
||||
:width: 60%
|
||||
:alt: Instructions
|
||||
|
||||
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.
|
||||
|
||||
|
||||
@@ -4,6 +4,10 @@
|
||||
Service Package Overview
|
||||
========================
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
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.
|
||||
@@ -14,7 +18,7 @@ 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>`_
|
||||
|
||||
@@ -34,7 +38,7 @@ 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.
|
||||
|
||||
@@ -43,7 +47,7 @@ Because the service ultimately runs on a Raspberry Pi, the created Docker image
|
||||
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.
|
||||
|
||||
@@ -53,7 +57,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.
|
||||
|
||||
@@ -66,7 +70,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 <service-dependencies>` key in the service manifest.
|
||||
|
||||
Manifest
|
||||
........
|
||||
========
|
||||
|
||||
This file describes the service and its requirements. It is used to:
|
||||
|
||||
@@ -81,19 +85,19 @@ 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 a detailed walkthrough of this example, please see the :ref:`Packaging Example<packaging-example>`.
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ Linux
|
||||
|
||||
sudo systemctl restart tor
|
||||
|
||||
.. group-tab:: Arch / Manjaro
|
||||
.. group-tab:: Arch / Manjaro / Garuda
|
||||
|
||||
Simply install Tor with:
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _initial-setup:
|
||||
|
||||
=============
|
||||
Initial Setup - ***COMPACT / SIMPLIFY??***
|
||||
Initial Setup
|
||||
=============
|
||||
|
||||
Connect and Power Up
|
||||
|
||||
@@ -1,9 +1,13 @@
|
||||
.. _recover-02x:
|
||||
|
||||
===================================
|
||||
Migrate Embassy from Versions 0.2.x - **NEEDS SCREENS**
|
||||
Migrate Embassy from Versions 0.2.x
|
||||
===================================
|
||||
|
||||
.. contents::
|
||||
:depth: 4
|
||||
:local:
|
||||
|
||||
Migrate Embassy Series 0.2.x Data
|
||||
---------------------------------
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _shoot-embassy:
|
||||
|
||||
=======================
|
||||
Troubleshooting Embassy - ***ADD LIST OF SOUNDS***
|
||||
Troubleshooting Embassy
|
||||
=======================
|
||||
|
||||
Hardware
|
||||
@@ -11,7 +11,7 @@ Embassy is making noises
|
||||
========================
|
||||
The plug and play Embassy sold by Start9 has no moving parts, so the only noises it should ever make would come from its internal speaker. The following is a list of all possible sounds:
|
||||
|
||||
#.
|
||||
#.
|
||||
|
||||
Embassy boots into "Diagnostic Mode"
|
||||
====================================
|
||||
|
||||
@@ -4,3 +4,68 @@
|
||||
SSH Over Tor
|
||||
============
|
||||
|
||||
.. note:: The following guide requires that you have already added an `SSH key to your Embassy<ssh-setup>`.
|
||||
|
||||
This is currently only supported on Linux, but may work on Windows with `Torifier <https://torifier.com/>`_.
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
#. First, you'll need one dependency, ``torsocks``, which will allow you to use SSH over Tor on the machine that you want access with. Select your Linux flavor to install:
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Debian / Ubuntu
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
apt install torsocks
|
||||
|
||||
.. group-tab:: Arch / Manjaro / Garuda
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S torsocks
|
||||
|
||||
#. SSH in:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ssh root@embassy-xxxxxxx.local
|
||||
|
||||
#. Add the following 2 lines to ``/etc/tor/torrc`` **EITHER** by using your preferred text editor:
|
||||
|
||||
``HiddenServiceDir /var/lib/tor/ssh``
|
||||
``HiddenServicePort 22 127.0.0.1:22``
|
||||
|
||||
**OR** by entering the following 2 commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
echo "HiddenServiceDir /var/lib/tor/ssh" >> /etc/tor/torrc
|
||||
echo "HiddenServicePort 22 127.0.0.1:22" >> /etc/tor/torrc
|
||||
|
||||
#. Then reload the Tor configuration with your edits:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl reload tor
|
||||
|
||||
#. Next, gather the ``.onion`` address you just created:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cat /var/lib/tor/ssh/hostname
|
||||
|
||||
.. note:: All these changes are on the overlay and won't persist after a restart of your Embassy
|
||||
|
||||
#. Add an additional SSH key in your EmbassyUI if you want to access from a machine other than the one you did this setup with.
|
||||
|
||||
Access
|
||||
------
|
||||
|
||||
Now to log in, simply use the following command, using the ``.onion`` hostname you printed above:
|
||||
|
||||
.. code-block::
|
||||
|
||||
torsocks ssh root@xxxxxxxxxxxxxxxxx.onion
|
||||
|
||||
Reference in New Issue
Block a user