mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
Walkthrough, services complete. Misc edits
This commit is contained in:
kn0wmad
@@ -1,4 +1,4 @@
|
||||
.. _service_config:
|
||||
.. _service-config:
|
||||
|
||||
============================
|
||||
Service Config Specification
|
||||
@@ -508,7 +508,7 @@ Example:
|
||||
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.
|
||||
This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules.
|
||||
|
||||
A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser.
|
||||
|
||||
|
||||
@@ -38,7 +38,7 @@ 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 <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 <service-manifest>` configuration file.
|
||||
|
||||
The image is immutable, meaning that when the service is updated, the image is replaced with a completely new image containing the updated features.
|
||||
|
||||
@@ -63,7 +63,7 @@ This may sound cool or neat, but it is more than that: *it’s novel*. This has
|
||||
|
||||
The key to making the system work is a new, domain-specific-language (DSL) and set of standards that are used by developers to define the rules and requirements of their services. Run in the context of EmbassyOS, these rules and requirements appear as simple UI elements, such as inputs, toggles, and drop downs, and they are enforced by validations and clear user instructions. Using this system, what previously required involved time and expertise, can now be done by anyone in a matter of seconds.
|
||||
|
||||
This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <dependencies>` key in the service manifest.
|
||||
This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <service-dependencies>` key in the service manifest.
|
||||
|
||||
Manifest
|
||||
........
|
||||
@@ -83,7 +83,7 @@ There is nothing you need to do as a developer to enable the service to run over
|
||||
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.
|
||||
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.
|
||||
|
||||
|
||||
@@ -24,7 +24,9 @@ One thing is for certain though: if you control your server, then you control yo
|
||||
|
||||
Why do I care?
|
||||
--------------
|
||||
As an example, let's talk about the password manager, Bitwarden. It may help convey the concept of a personal server. Currently, when you use Bitwarden, your passwords are stored on a physical device (aka server) owned and operated by the Bitwarden team. Your phone or laptop sends requests to their server when you want to do anything: create an account, create a new password, retrieve existing passwords, etc. Your passwords are stored on their device, encrypted with your Bitwarden password. They are the custodian of your passwords, similar to getting a safe deposit box at the bank. The bank keeps your valuables in their vault, presumably they don't know what's in the box, and any time you want access to your box, you ask the bank for permission. This is exactly how a hosted Bitwarden experience works, as well as just about everything on the internet. When you install Bitwarden on your Embassy, by contrast, it's like building your own safe deposit box in a private bunker whose location is only known to you and whose keys only you posses. You create an account with yourself, store your passwords with yourself, etc. You are your own custodian. This same concept can be applied to just about everything on the Internet, without losing the convenience of the custodial model, which is what we are out to accomplish. This may sound cool, or neat, but it is so much more than that. The custodial data model is amongst the greatest threats to human liberty the world has ever seen.
|
||||
As an example, let's talk about the password manager, Bitwarden. It may help convey the concept of a personal server. Currently, when you use Bitwarden, your passwords are stored on a physical device (aka server) owned and operated by the Bitwarden team. Your phone or laptop sends requests to their server when you want to do anything: create an account, create a new password, retrieve existing passwords, etc. Your passwords are stored on their device, encrypted with your Bitwarden password. They are the custodian of your passwords, similar to getting a safe deposit box at the bank. The bank keeps your valuables in their vault, presumably they don't know what's in the box, and any time you want access to your box, you ask the bank for permission. This is exactly how a hosted Bitwarden experience works, as well as just about everything on the internet.
|
||||
|
||||
When you install Bitwarden on your Embassy, by contrast, it's like building your own safe deposit box in a private bunker whose location is only known to you and whose keys only you posses. You create an account with yourself, store your passwords with yourself, etc. You are your own custodian. This same concept can be applied to just about everything on the Internet, without losing the convenience of the custodial model, which is what we are out to accomplish. This may sound cool, or neat, but it is so much more than that. The custodial data model is amongst the greatest threats to human liberty the world has ever seen.
|
||||
|
||||
This `podcast <https://www.youtube.com/watch?v=aylDowaSdzU&t=270s>`_ may help expound upon why this is important.
|
||||
|
||||
@@ -44,7 +46,7 @@ The list of services will grow rapidly over the coming months, such that many th
|
||||
|
||||
What is EmbassyOS?
|
||||
------------------
|
||||
EmbassyOS is a new kind of Operating System (OS). It is built from the ground up to allow anyone to easily run their own ‘cloud,’ become independent from Big Tech, and own their own data. EmbassyOS allows anyone to easily self-host their own software services.
|
||||
EmbassyOS is a new kind of Operating System (OS). It is built from the ground up to allow anyone to easily run their own "cloud," become independent from Big Tech, and own their own data. EmbassyOS allows anyone to easily self-host their own software services.
|
||||
|
||||
EmbassyOS is a custom-built Linux distribution, which is a stripped down and beefed up version of `Raspbian Buster Lite OS <https://www.raspberrypi.org/software/operating-systems/>`_, along with a suite of software tools which make it easy to:
|
||||
|
||||
@@ -62,7 +64,7 @@ The .s9pk extension is Start9's custom package format based on tar. It encompass
|
||||
|
||||
What are EmbassyOS Services?
|
||||
----------------------------
|
||||
A Service can be any piece of software added to the Marketplace. All services are "self-hosted," meaning that you are in complete control of your data. This means you can run your own "cloud!" Learn more about managing services :ref:`here <managing-services>` and see our currently :ref:`Available Services <available-services>`.
|
||||
A Service can be any piece of software added to the Marketplace. All services are "self-hosted," meaning that you are in complete control of your data. This means you can run your own "cloud!" Learn more about managing services :ref:`here <managing-services>` and see our currently :ref:`Available Services <service-marketplace>`.
|
||||
|
||||
Does the Embassy ship worldwide?
|
||||
--------------------------------
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _config:
|
||||
|
||||
=============
|
||||
Configuration
|
||||
=============
|
||||
@@ -11,4 +13,5 @@ Configuration, setup guides, and known limitations are provided here by device.
|
||||
tor-setup/index
|
||||
lan-setup/index
|
||||
wifi
|
||||
sessions
|
||||
limitations/index
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
.. _sessions:
|
||||
|
||||
===============
|
||||
Active Sessions
|
||||
===============
|
||||
|
||||
@@ -13,6 +13,7 @@ An overview of Services and Marketplaces on EmbassyOS.
|
||||
service-install
|
||||
service-config
|
||||
service-instructions
|
||||
service-properties
|
||||
service-actions
|
||||
service-interfaces
|
||||
service-logs
|
||||
|
||||
@@ -9,8 +9,6 @@ Currently, this is a link provided by the service package developer so that you
|
||||
.. figure:: /_static/images/services/donate.svg
|
||||
:width: 60%
|
||||
|
||||
Donate
|
||||
|
||||
.. topic-box::
|
||||
:title: Looking Forward
|
||||
|
||||
|
||||
@@ -1,7 +1,15 @@
|
||||
.. _interfaces:
|
||||
.. _service-interfaces:
|
||||
|
||||
==========
|
||||
Interfaces
|
||||
==========
|
||||
|
||||
Interfaces are URLs that a :ref:`Service<services>` uses to communicate in various ways with other software. Many Services will only have one interface, perhaps with a Tor and LAN address, to denote where it is hosted / accessed. Other services, such as Bitcoin or Lightning Nodes, may have several interfaces for different use-cases.
|
||||
|
||||
.. figure:: /_static/images/services/service-ints.svg
|
||||
:width: 60%
|
||||
|
||||
To view the instructions for a particular service, navigate to the :ref:`Services tab <services-tab>` *> [Service Name] > Properties*. From there you can copy a URL to your clipboard for use with external software.
|
||||
|
||||
.. figure:: /_static/images/services/service-ints0.svg
|
||||
:width: 60%
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
.. _logs:
|
||||
.. _service-logs:
|
||||
|
||||
====
|
||||
Logs
|
||||
@@ -6,4 +6,7 @@ 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.
|
||||
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. You can check here if you have an issue with a service, and if you are talking to support, they may ask you to screenshot or copy these logs to help discover the root of the problem.
|
||||
|
||||
.. figure:: /_static/images/services/logs.svg
|
||||
:width: 60%
|
||||
|
||||
@@ -6,6 +6,7 @@ Services Overview
|
||||
|
||||
Services are very similar to Applications on a mobile device. The biggest differences are that they are often designed to run constantly, with 24/7 availability for when a user requires them. This is why they are called :ref:`Services<services>`, they are always ready to serve users!
|
||||
|
||||
.. _service-page:
|
||||
|
||||
The Service Page
|
||||
----------------
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
.. _properties:
|
||||
|
||||
==========
|
||||
Properties
|
||||
==========
|
||||
|
||||
Navigate to *Services > [Service Name] > Properties*
|
||||
|
||||
Properties are both static and dynamic information about a service. They could be almost anything: a default username/password, an invite code, or a list of peers - anything the service developer thought might be useful.
|
||||
|
||||
Properties may be accompanied by one or more of the following:
|
||||
|
||||
* a *help* icon for further explanation.
|
||||
* a *copy* icon for copying the value to your clipboard.
|
||||
* a *QR* icon for viewing the value as a QR code.
|
||||
@@ -0,0 +1,20 @@
|
||||
.. _service-properties:
|
||||
|
||||
==========
|
||||
Properties
|
||||
==========
|
||||
|
||||
Properties can contain both static and dynamic information about a service. They could be almost anything: a default username/password, an invite code, or a list of peers - anything the service developer thought might be useful.
|
||||
|
||||
.. figure:: /_static/images/services/props.svg
|
||||
:width: 60%
|
||||
|
||||
To view the instructions for a particular service, navigate to the :ref:`Services tab <services-tab>` *> [Service Name] > Properties*.
|
||||
|
||||
Properties may be accompanied by one or more of the following:
|
||||
|
||||
* a *help* icon for further explanation.
|
||||
* a *copy* icon for copying the value to your clipboard.
|
||||
* a *QR* icon for viewing the value as a QR code.
|
||||
|
||||
.. note:: Some services do not have any information in the Properties section
|
||||
@@ -1,9 +1,9 @@
|
||||
.. _updates:
|
||||
.. _service-updates:
|
||||
|
||||
========
|
||||
Updating
|
||||
========
|
||||
|
||||
To see if an update is available for a service, you can visit the *updates* section of the Marketplace or by visiting its Marketplace listing.
|
||||
To see if an update is available for a service, you can visit the *Updates* section of the Marketplace or by visiting its Marketplace listing.
|
||||
|
||||
If an update is available, simply click "Update" and confirm the action.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _overview:
|
||||
|
||||
=====================
|
||||
Overview of EmbassyOS - ***NEED SCREENSHOTS / DETAILS***
|
||||
Overview of EmbassyOS
|
||||
=====================
|
||||
|
||||
.. _services-tab:
|
||||
@@ -11,8 +11,13 @@ Services Tab
|
||||
|
||||
The Services Tab will show you all of your currently installed :ref:`Services<services>`, or in the case of a fresh install, no Services.
|
||||
|
||||
Services
|
||||
========
|
||||
.. figure:: /_static/images/walkthrough/servicestab.svg
|
||||
:width: 60%
|
||||
|
||||
Click on any service in order to see its :ref:`Service Page<service-page>`.
|
||||
|
||||
.. figure:: /_static/images/walkthrough/servicepage.svg
|
||||
:width: 60%
|
||||
|
||||
.. _embassy-tab:
|
||||
|
||||
@@ -21,22 +26,25 @@ Embassy Tab
|
||||
|
||||
The Embassy Tab is where you can perform :ref:`Backups<backups>`, get Insights into EOS, change some basic Settings, and Power cycle your device if necessary.
|
||||
|
||||
.. figure:: /_static/images/walkthrough/embassytab.svg
|
||||
:width: 60%
|
||||
|
||||
.. _backups:
|
||||
|
||||
Backups
|
||||
=======
|
||||
|
||||
Do the backups
|
||||
One of the most important actions you can do on your Embassy is to keep a regular backup of your data. See the following page on :ref:`Backups<backup>`, and select your device for more details.
|
||||
|
||||
Insights
|
||||
========
|
||||
|
||||
Get the insights
|
||||
The Insights section gives you basic information on your Embassy, monitoring of system resources / temperature, and logs for debugging.
|
||||
|
||||
Settings
|
||||
========
|
||||
|
||||
Set the things
|
||||
The Settings section lets you change preferences, and manage `Connectivity` and Active Sessions. See the documentation on :ref:`Configuration<config>` for more details.
|
||||
|
||||
Power
|
||||
=====
|
||||
@@ -51,7 +59,7 @@ Restart
|
||||
Shutdown
|
||||
........
|
||||
|
||||
#. Be patient while services shut down. A *tune* will play, indicating the shutdown is complete.
|
||||
#. Be patient while services shut down, it may take some minutes. 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.
|
||||
@@ -61,7 +69,10 @@ Shutdown
|
||||
Marketplace Tab
|
||||
---------------
|
||||
|
||||
The Marketplace Tab is obviously the home of the Marketplace, where you can install new Services, or manange existing ones.
|
||||
The Marketplace Tab is obviously the home of the Marketplace, where you can search out and install new Services, or manange existing ones. You can view our live Marketplace `here <marketplace.start9.com>`_.
|
||||
|
||||
.. figure:: /_static/images/walkthrough/markettab.svg
|
||||
:width: 60%
|
||||
|
||||
Marketplace
|
||||
===========
|
||||
@@ -71,12 +82,7 @@ Marketplace
|
||||
Notifications Tab
|
||||
-----------------
|
||||
|
||||
The Notifications Tab is where you can view and manage Notifications produced by EOS and your Services
|
||||
The Notifications Tab is where you can view and manage information produced by EOS and your Services that may need your attention. You can clear these individually, or all at once with ``Delete All`` in the top right.
|
||||
|
||||
Notifications
|
||||
=============
|
||||
|
||||
* successful or failed EmbassyOS updates
|
||||
* successful or failed service installations
|
||||
* successful or failed service backups
|
||||
* successful or failed service updates
|
||||
.. figure:: /_static/images/walkthrough/notiftab.svg
|
||||
:width: 60%
|
||||
|
||||
Reference in New Issue
Block a user