SDK, dev docs images, SSH-over-Tor, Misc edits

site/03-todo.md

@@ -17,22 +17,11 @@
 - [ ] Configuration
     - LAN Setup
         - Android - Screenshots of LAN setup and verify steps on an Android 12+ device
-        - Brave
         - Chrome
         - Firefox
 - [ ] Tuning
     - DIY Guide
-    - Advanced Config
-        - SSH over Tor
     - Service-specific Guides
-- [ ] Developer Documentation
-    - embassy-sdk
-    - Service Packaging Spec
-    - Service Packaging Walkthrough (Hello-World Example)
-    - Development FAQ
-        - Contributing
-        - Service Packaging
-
 - [ ] Alt Market Build Guide
 - [ ] Mission / values
 - [ ] Backups

site/source/support/dev-docs/dev-tools/embassy-sdk.rst

@@ -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
+        cargo install --bin=embassy-sdk --path=. --no-default-features --verbose
-
-..         embassy-cli auth login
-
-..     and enter your Embassy Master Password at the prompt.
 
 
-.. 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:
+        USAGE:
-..             embassy-cli [OPTIONS] <SUBCOMMAND>
+            embassy-sdk [OPTIONS] <SUBCOMMAND>
 
-..         FLAGS:
+        FLAGS:
-..                 --help       Prints help information
+            -h, --help       Prints help information
-..             -V, --version    Prints version information
+            -V, --version    Prints version information
 
-..         OPTIONS:
+        OPTIONS:
-..             -c, --config <config>
+            -c, --config <config>
-..             -h, --host <host>
-..             -p, --proxy <proxy>
 
-..         SUBCOMMANDS:
+        SUBCOMMANDS:
-..             auth            Login/logout and manage sessions
+            git-info    Print current git hash
-..             backup          Manage backups
+            help        Prints this message or the help of the given subcommand(s)
-..             db              Interact with the Database
+            init        Initialize
-..             disk            Information on the external drive
+            inspect     Inspect a .s9pk
-..             echo            Echoes
+            pack        Package a service into the .s9pk format
-..             git-info        Print the current git hash
+            verify      Verify a .s9pk is valid
-..             help            Prints this message or the help of the given subcommand(s)
+
-..             inspect         Details on services and their components
+
-..             net             Network information
+Please visit https://github.com/Start9Labs/embassy-os/tree/master/backend for more details
-..             notification    Control UI notifications
-..             package         Interact with packages
-..             server          EmbassyOS operations and information
-..             ssh             Manage SSH keys
-..             wifi            Manage WiFi networks

site/source/support/dev-docs/index.rst

@@ -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.

site/source/support/dev-docs/packaging-example.rst

@@ -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
 --------
@@ -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.
 

site/source/support/dev-docs/service-packaging/overview.rst

@@ -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>`.
 

site/source/support/user-manual/configuration/tor-setup/tor-os/tor-linux.rst

@@ -30,7 +30,7 @@ Linux
 
                 sudo systemctl restart tor
 
-    .. group-tab:: Arch / Manjaro
+    .. group-tab:: Arch / Manjaro / Garuda
 
         Simply install Tor with:
 

site/source/support/user-manual/getting-started/initial-setup.rst

@@ -1,7 +1,7 @@
 .. _initial-setup:
 
 =============
-Initial Setup - ***COMPACT / SIMPLIFY??***
+Initial Setup
 =============
 
 Connect and Power Up

site/source/support/user-manual/getting-started/recover-02.rst

@@ -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
 ---------------------------------
 

site/source/support/user-manual/troubleshooting/shoot-embassy.rst

@@ -1,7 +1,7 @@
 .. _shoot-embassy:
 
 =======================
-Troubleshooting Embassy - ***ADD LIST OF SOUNDS***
+Troubleshooting Embassy
 =======================
 
 Hardware

site/source/support/user-manual/tuning/advanced-config/ssh-tor.rst

@@ -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