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

Dev tools init, config edits, misc edits

Browse Source
This commit is contained in:
kn0wmad
2022-01-16 00:28:31 -07:00
committed by Lucy Cifferello
parent 5c10c17204
commit a5fe40e84a
19 changed files with 286 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
site/03-todo.md
View File

@@ -1,16 +1,18 @@
# ToDo
- Transfer HTML or refactor: Roadmap
- Document diagnostic UI
- Update principles, privacy, about, etc
- Footer links need update (or removal?)
- Add screenshots and details
- Verify ALL links and TOCs
- Add / verify ALL links in the UI go to the right place in docs
- There are many issues that should be closed by 0.3 docs release, check that this is the case (some issues await new processes in order to test)
- Update all guides in services
- Launch versioned site/docs to start9.com
- Address build errors
- [ ] Refactor and update Roadmap
- [ ] Document colours
- [ ] Document diagnostic UI
- [ ] Update principles, privacy, about, etc
- [ ] Footer links need update (or removal?)
- [ ] Add screenshots and details
- [ ] Verify ALL links and TOCs
- [ ] Check all menus behave and display as expected
- [ ] Add / verify ALL links in the UI go to the right place in docs
- [ ] Update all guides in service repos
- [ ] Address build errors
- [ ] Launch versioned site/docs to start9.com
- [ ] There are many issues that should be closed by 0.3 docs release, check that this is the case (some issues await new processes in order to test)
<!-- Checklist
# User Manual
@@ -22,33 +24,25 @@
- Change to topic or hero boxes
- (after release) create badges
- Configuration
- Tor Setup
- Desktop
- Linux
- Mac
- Windows
- Mobile
- Android
- iOS
- Browser
- FF Desktop
- FF Mobile
- LAN Setup
- Desktop
- Linux
- Mac
- Windows
- Mobile
- Android
- iOS
- Platform Limitations
- Desktop
- Linux
- Mac
- Windows
- Mobile
- Android
- iOS
- Tor Setup
- Desktop
- Linux
- Mac
- Windows
- Mobile
- Android
- iOS
- Browser
- FF Desktop
- FF Mobile
- LAN Setup
- Desktop
- Linux
- Mac
- Windows
- Mobile
- Android
- iOS
- Tuning
- DIY Guide
- Hardware
@@ -57,34 +51,19 @@
- From Umbrel
- Advanced Configurations
- SSH over Tor
- Exec into a Service
- EmbassyOS
- Service-specific Guides
- Connecting External Services
- Bitcoin Wallets
- FullyNoded
- Specter
- Sparrow
- Lightning Wallets
- Spark
- Zap
- Zeus
- Troubleshooting
- Connection
- Embassy
- Hardware
- Software
# Learn
- Concepts
- FAQ
- FAQ - remove anything no longer relevant in 0.3
- Embassy
- Device
- OS
- DIY
# Developer Documentation
- Service Packaging Guide
- embassyd
- embassy-sdk
- Service Packaging Spec
- Overview
- Wrapper
- Manifest
@@ -99,5 +78,4 @@
- Development FAQ
- Contributing
- Service Packaging
-->

BIN
site/source/_static/images/walkthrough/sessions0.svg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 82 KiB

14
site/source/learn/concepts/embassy.rst
View File

@@ -34,6 +34,18 @@ 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.
.. _sessions:
Session
-------
A session is simply a logged-in connection to your Embassy. You can view your :ref:`Active Sessions<active-sessions>`, and kill one if you suspect it is not legitimate, or no longer use it.
.. _service-container:
Service Container
-----------------
Each service is compartmentalilzed into its own "container," at this time, this normally means a `Docker <docker.com>`_ container. There are several reasons for this, including security, ease of use, and maintenance.
.. _service-dependencies:
Dependencies
@@ -70,3 +82,5 @@ Health Checks
One of the most critical duties of a sysadmin or devops engineer is to build systems to monitor health. For example, a simple health check that monitors the availability of an LND node could mean the difference between that node having a poor reputation or a great one. Sometimes, it is not obvious when a service is unhealthy, especially since “health” is a subjective term depending on the subject. For example, is your Bitcoin node “healthy” if it is not fully synced? Is it healthy if the user interface is unreachable but everything else is working ok?
In EmbassyOS 0.3.0, package developers define what constitutes health and implement health checks according to subjective criteria that are then displayed to the user in easily digestible messages, complete with icons and colors. Even better, health checks are completely arbitrary and turing complete, meaning they can include anything, including config options and internal or external dependencies! For example, a Lightning wallet package developer could say “this service is only healthy if (1) it is fully synced, (2) Bitcoin is fully synced, (3) LND is fully synced, and (4) if and only if the user has opted for real-time pricing from a third party website, that third party website must be reachable.” Enormous power.

52
site/source/support/dev-docs/dev-tools/embassy-cli.rst Normal file
View File

@@ -0,0 +1,52 @@
.. _embassy-cli:
===========
Embassy-CLI
===========
.. warning:: This is for advanced users only!! Anything you do while SSH'd into your Embassy is NOT SUPPORTED, unless under the guidance of a Start9 technician.
When interacting with Embassy directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control EmbassyOS in many of the same ways that the UI can, but with finer controls and deeper insights.
In order to use Embassy-CLI, you will first need to authorize yourself with the following command...
.. code-block:: bash
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:
.. code-block:: bash
Embassy CLI
USAGE:
embassy-cli [OPTIONS] <SUBCOMMAND>
FLAGS:
--help Prints help information
-V, --version Prints version information
OPTIONS:
-c, --config <config>
-h, --host <host>
-p, --proxy <proxy>
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

52
site/source/support/dev-docs/dev-tools/embassy-sdk.rst Normal file
View File

@@ -0,0 +1,52 @@
.. _embassy-sdk:
===========
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.
.. In order to use Embassy-CLI, you will first need to authorize yourself with the following command...
.. .. code-block:: bash
.. 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:
.. .. code-block:: bash
.. Embassy CLI
.. USAGE:
.. embassy-cli [OPTIONS] <SUBCOMMAND>
.. FLAGS:
.. --help Prints help information
.. -V, --version Prints version information
.. OPTIONS:
.. -c, --config <config>
.. -h, --host <host>
.. -p, --proxy <proxy>
.. 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

52
site/source/support/dev-docs/dev-tools/embassyd.rst Normal file
View File

@@ -0,0 +1,52 @@
.. _embassyd:
========
EmbassyD
========
.. warning:: This is for advanced users only!! Anything you do while SSH'd into your Embassy is NOT SUPPORTED, unless under the guidance of a Start9 technician.
.. When interacting with Embassy directly, you will invariably want to use ``embassy-cli``. Embassy-CLI can control EmbassyOS in many of the same ways that the UI can, but with finer controls and deeper insights.
.. In order to use Embassy-CLI, you will first need to authorize yourself with the following command...
.. .. code-block:: bash
.. 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:
.. .. code-block:: bash
.. Embassy CLI
.. USAGE:
.. embassy-cli [OPTIONS] <SUBCOMMAND>
.. FLAGS:
.. --help Prints help information
.. -V, --version Prints version information
.. OPTIONS:
.. -c, --config <config>
.. -h, --host <host>
.. -p, --proxy <proxy>
.. 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

15
site/source/support/dev-docs/dev-tools/index.rst Normal file
View File

@@ -0,0 +1,15 @@
.. _dev-tools:
===============
Developer Tools
===============
Brief overviews of Developer Tools that will come in handy when :ref:`packaging a service<service-packaging>`, or interacting directly with the OS to learn or contribute to the project.
.. toctree::
:maxdepth: 2
embassyd
embassy-cli
embassy-sdk
service-container

19
site/source/support/dev-docs/dev-tools/service-container.rst Normal file
View File

@@ -0,0 +1,19 @@
.. _service-container:
=========================
Enter a Service Container
=========================
For simplicity, EmbassyOS is designed to be completely operated via the :ref:`WebUI<web-ui>`, however, your device belongs to you and if you want to "lift the hood" and access the internals of the software, you may do so. This guide will show you how to enter a Service's :ref:`container<containers>` in order to directly interface with it and issue commands.
.. warning:: The following guide is for those that have advanced command line skills, or those who are being guided by a Start9 support technician. Nothing you do inside a container is supported unless under the direction of Start9. Here be dragons!!
This guide assumes you already have :ref:`SSH Access<ssh-setup>` setup on your machine.
Open a terminal, ssh into your device, and enter the following command, replacing ``<SERVICE>`` with the name of the service you are trying to access. You can list the services with ``embassy-cli package list`` (you will need to be logged in under ``embassy-cli`` for this). You will need to either be ``root`` or use ``sudo``.
.. code-block:: bash
docker exec -it <SERVICE>.embassy sh
This will give you a shell within the container. Reminder that nothing you do in here is supported, please be careful!

2
site/source/support/dev-docs/index.rst
View File

@@ -9,6 +9,7 @@ Developer Docs
:hidden:
dev-faq/index
dev-tools/index
service-packaging/index
packaging-example
@@ -18,5 +19,6 @@ Developer 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.

2
site/source/support/user-manual/configuration/lan-setup/index.rst
View File

@@ -1,7 +1,7 @@
.. _lan-setup:
============
Local Access - **UPDATES REQUIRED**
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. Begin by setting up :ref:`Devices<lan-os>` before setting up a :ref:`Browser<lan-browser>`.

3
site/source/support/user-manual/configuration/lan-setup/lan-os/lan-android.rst
View File

@@ -4,3 +4,6 @@
Android
=======
If you are running Android 12, you can setup :ref:`Local Access<lan>`, please see :ref:`Android Limitations <lim-android>` for more details on devices that have this capability.

2
site/source/support/user-manual/configuration/lan-setup/lan-os/lan-linux.rst
View File

@@ -1,7 +1,7 @@
.. _lan-linux:
=====
Linux - ***UPDATE SCREENS***
Linux
=====
Nothing specific needs to be configured for this environment, so you just need the certificate from your Embassy.

4
site/source/support/user-manual/configuration/limitations/lim-android.rst
View File

@@ -6,8 +6,8 @@ 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).
Older versions of Android (previous to version 12, and some custom ROMs, such as Graphene/Calyx) do 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.

4
site/source/support/user-manual/configuration/limitations/lim-ios.rst
View File

@@ -9,7 +9,7 @@ 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
@@ -17,5 +17,5 @@ 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 when `Element <https://github.com/vector-im/element-ios>`_ builds Tor into their app. An issue specifically in regard to this can be found `here <https://github.com/vector-im/element-ios/issues/1085>`_.
Workarounds
...........
===========
None currently known.

8
site/source/support/user-manual/configuration/sessions.rst
View File

@@ -1,6 +1,12 @@
.. _sessions:
.. _active-sessions:
===============
Active Sessions
===============
Every time a login is made with Embassy, such as from a web browser on your laptop or mobile device, a :ref:`Session <sessions>` is created. You can see these listed in the ``Embassy`` tab, under ``Active Sessions``.
To end a session, simply click ``Kill`` to the right of your selection.
.. figure:: /_static/images/walkthrough/sessions0.svg
:width: 60%

34
site/source/support/user-manual/getting-started/device-guides/dg-windows.rst
View File

@@ -4,24 +4,32 @@
Windows
=======
.. note:: Please see Window's :ref:`Known Limitations<lim-windows>` to understand what is currently not possible on these devices
.. note:: Please see Window's :ref:`Known Limitations<lim-windows>` to understand what is currently not possible on these devices.
LAN Setup (Connectivity, Performance)
-------------------------------------
.. topic-box::
:title: LAN Setup (Connectivity, Performance)
:link: https://start9.com/latest/support/user-manual/configuration/lan-setup/lan-windows
:anchor: Setup
`Setup LAN Access <https://docs.start9.com/support/user-manual/configuration/lan-setup/lan-windows>`_ for a fast and secure connection while on your Embassy's local network.
For a fast and secure connection while on your Embassy's local network
Tor Setup (Connectivity)
------------------------
.. topic-box::
:title: Tor Setup (Connectivity)
:link: https://start9.com/latest/support/user-manual/configuration/tor-setup/tor-os/tor-windows
:anchor: Setup
`Setup Tor <https://docs.start9.com/support/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.
Run Tor natively (in the background) on your device. This will allow you to use applications on your Windows machine via the Tor Network so they can communicate with your Embassy.
Tor Firefox Config (Connectivity)
---------------------------------
.. topic-box::
:title: Tor Firefox Config (Connectivity)
:link: https://start9.com/latest/support/user-manual/configuration/tor-setup/tor-firefox/torff-windows
:anchor: Configure
`Configure Firefox <https://docs.start9.com/support/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.
Configure Firefox to use the Tor Network so that you can reach ``.onion`` sites without needing to change browsers.
Embassy Backups (Reliability)
-----------------------------
.. topic-box::
:title: Embassy Backups (Resilience)
:link: https://start9.com/latest/support/user-manual/walkthrough/backup/backup-win
:anchor: Backup
`Configure Remote Backup <https://docs.start9.com/support/user-manual/walkthrough/backup/backup-win>`_ of your Embassy to your Windows machine. **Backups are supremely important** as they ensure redundancy of your data for convenience, as well as preventing loss in case of disaster.
Configure remote backups of your Embassy to your Windows machine. **Backups are supremely important** as they ensure redundancy of your data for convenience, as well as preventing loss in case of disaster.

3
site/source/support/user-manual/getting-started/recover-03.rst
View File

@@ -7,8 +7,11 @@ Recover Embassy from Versions 0.3.x
Recover Embassy Series 0.3.x Data
---------------------------------
This guide will cover how to recover existing EmbassyOS version 0.3.x data.
Recover From Remote Backup
==========================
Recover From Local (External Drive) Backup
==========================================

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

@@ -8,18 +8,18 @@ Hardware
--------
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 will not boot
.....................
=====================
If the device will not power on at all (no lights whatsoever), then the only issues could be that the Pi is not getting the power it needs, or it is completely dead (extremely rare). If you sourced your own parts, please ensure that the power supply meets the minimum required specificiations in the `DIY Guide<diy>`. If you received your device from us and it will not power up at all, please `Contact us<contact>` for assistance.
Software
--------
I'm having an issue with a particular Service
.............................................
=============================================
If a Service is crashing or acting up in some way, check the `Documentation<services>` and `FAQ<faq-services>` for that particular Service. You can also check the `Logs` of a service, which might tell you what the problem is. If that is not helpful, try to restart the service to see if that clears up the issue. If you are still having issues, please reach out in one of our `Community Channels` for immediate assistance, or email support@start9labs.com for help during business hours.

2
site/source/support/user-manual/tuning/advanced-config/ssh-setup.rst
View File

@@ -4,7 +4,7 @@
SSH Setup
=========
.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause through SSH access.
.. warning:: This is an advanced feature and should be used with caution. Start9 is not responsible for any damage you might cause while using SSH access.
Connecting via CLI (Linux / Mac)
--------------------------------