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

Misc edits

Browse Source
This commit is contained in:
kn0wmad
2022-01-04 16:47:53 -07:00
committed by Lucy Cifferello
parent 94ec70d684
commit 8d9a8894c5
7 changed files with 105 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
site/03-todo.md
View File

@@ -1,11 +1,15 @@
- Transfer HTML or refactor: Roadmap, News (now media/articles and media/podcasts) # ToDo
- Transfer HTML or refactor: Roadmap
- Update principles, privacy, about, etc - Update principles, privacy, about, etc
- Footer links need update (or removal?) - Footer links need update (or removal?)
- Lots of screenshots and details - Add screenshots and details
- Verify ALL links and TOCs - Verify ALL links and TOCs
- Add / verify ALL links in the UI go to the right place in docs - 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) - 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 - Update all guides in services
- Launch versioned site/docs to start9.com
- Address build errors after versioning is live
<!-- Original Layout (deprecated) <!-- Original Layout (deprecated)
# User Manual # User Manual

1
site/source/about/index.rst
View File

@@ -94,5 +94,6 @@
roadmap roadmap
privacy privacy
license license
team
jobs jobs
contact contact

7
site/source/about/team.rst Normal file
View File

@@ -0,0 +1,7 @@
.. _team:
===============
The Start9 Team
===============
Please check back soon!!

25
site/source/support/dev-docs/dev-faq/faq-contributing.rst
View File

@@ -1,7 +1,7 @@
.. _faq-contributing: .. _faq-contributing:
============ ============
Contributing - **EXPAND** Contributing
============ ============
We ❤️ contributions! We ❤️ contributions!
@@ -10,20 +10,17 @@ Please follow the guide `here <https://github.com/Start9Labs/embassy-os/blob/mas
Do I need to be a professional developer or have coding experience to contribute? 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. 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 :ref:`Contact <contact>` us for ideas if you're not sure where to begin.
The guide says that a Makefile is optional, why is this?
--------------------------------------------------------
The ``Makefile`` simplifies the development process by putting all your build steps into one place so that you can simply use the ``make`` to build with. A ``Makefile`` is not required however, and you may instead choose to use something like ``nix``, ``bash``, ``perl``, ``python``, or ``ruby`` for your build orchestration.
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 .. Expound the following into FAQs:
- Alerts in LND example are not wrapped in quotes, same with CUPS release notes – yaml thing .. --------------------------------
- Ports in manifest – can leave as default (80), as it is a docker container?? - Sure
.. - 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
.. - Alerts in LND example are not wrapped in quotes, same with CUPS release notes – yaml thing
.. - 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?
.. - Config spec – Admin pass?
- Type definitions – is this just for dependencies? Can a blurb be added here for extra clarity?
- Config spec – Admin pass?
- Makefile
- Not required, but simplifies dev process

10
site/source/support/dev-docs/dev-faq/faq-service-packaging.rst
View File

@@ -5,7 +5,7 @@
:local: :local:
===================== =====================
Service Packaging FAQ - **EXPAND** Service Packaging FAQ
===================== =====================
Do I need programming experience to package a service for EmbassyOS? Do I need programming experience to package a service for EmbassyOS?
@@ -18,11 +18,11 @@ There are several things you will want to consider. Requirements include:
#. Most importantly, pick a service you are passionate about seeing on EmbassyOS #. Most importantly, pick a service you are passionate about seeing on EmbassyOS
#. Make sure it is :ref:`Open Source <open-source>` #. Make sure it is :ref:`Open Source <open-source>`
#. A service that incorporates a 'self-hosting' option, or is capable of being self-hosted
Recommendations that may ease the process: Recommendations that may ease the process:
#. A service that has already been 'dockerized' (has a **working** ``Dockerfile``) #. 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 written in a language you are familiar with
#. A service with a strong community #. A service with a strong community
@@ -30,9 +30,13 @@ You can check this expansive list if you are in search of ideas: `Awesome Self-H
What if I don't need a Config in my service? What if I don't need a Config in my service?
-------------------------------------------- --------------------------------------------
Config files can be empty(``{}``), if you do not require config. Config files can be empty( ``{}`` ), if you do not require config.
How can my service access the data directory of another service? How can my service access the data directory of another service?
---------------------------------------------------------------- ----------------------------------------------------------------
#. Provider service needs to expose datadir to other services on embassy #. 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 #. 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
The guide says that a Makefile is optional, why is this?
--------------------------------------------------------
The ``Makefile`` simplifies the development process by putting all your build steps into one place so that you can simply use the ``make`` to build with. A ``Makefile`` is not required however, and you may instead choose to use something like ``nix``, ``bash``, ``perl``, ``python``, or ``ruby`` for your build orchestration.

49
site/source/support/dev-docs/packaging-example.rst
View File

@@ -6,13 +6,13 @@ 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>`_. 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! 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.
Pre-requisites Pre-requisites
-------------- --------------
EmbassyOS (EOS) EmbassyOS (EOS)
............... ===============
It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service. It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service.
@@ -22,7 +22,7 @@ There are 3 options for this:
#. :ref:`Purchse <purchasing>` a device or copy of the OS #. :ref:`Purchse <purchasing>` a device or copy of the OS
Development Environment Development Environment
....................... =======================
Once you have EOS installed, you'll want to set up your development system with the necessary software. Once you have EOS installed, you'll want to set up your development system with the necessary software.
@@ -41,7 +41,7 @@ Overview
-------- --------
Components Components
.......... ==========
Simply, the package is made up of the following parts: 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. 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.
@@ -54,7 +54,7 @@ Simply, the package is made up of the following parts:
Check :ref:`here <service_package_overview>` for a detailed overview of package components. Check :ref:`here <service_package_overview>` for a detailed overview of package components.
Service Wrapper Repo and Submodules Service Wrapper Repo and Submodules
................................... ===================================
See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository. See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository.
@@ -72,7 +72,7 @@ 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. 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 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>`_) 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>`_)
@@ -86,7 +86,7 @@ Clone the Template Repo and Edit the Manifest
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: 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 Manifest example
................ ================
.. code-block:: yaml .. code-block:: yaml
@@ -247,7 +247,7 @@ Note the ``dependencies`` and ``volumes`` sections, which may access another ser
For details on all the different possible dependency, type, and subtype definitions available for the ``manifest`` file, please see :ref:`here <service_manifest>`. 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 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``. 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``.
@@ -303,7 +303,10 @@ Next, it's time to edit the ``Dockerfile``. This defines how to build the image
ENTRYPOINT ["/usr/local/bin/docker_entrypoint.sh"] 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: Docker Entrypoint
=================
1. 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. It's also PID 1 in the docker container, so it does all of the signal handling and container exits when it is stopped/exits. 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 .. code:: bash
@@ -313,14 +316,14 @@ Next, it's time to edit the ``Dockerfile``. This defines how to build the image
exec tini hello-world exec tini hello-world
7. We've defined the file, exported the IP address, and run the program. 2. 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>`_. 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) 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``. 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 ``nix``, ``bash``, ``python``, ``perl``, ``ruby``, etc instead of ``make`` for build orchestration.
Our example ``Makefile`` is agin fairly simple for Hello World. Let's take a look: Our example ``Makefile`` is agin fairly simple for Hello World. Let's take a look:
@@ -357,20 +360,20 @@ Our example ``Makefile`` is agin fairly simple for Hello World. Let's take a lo
2. The next line simply removes the progress of a ``make`` process if it fails. 2. The next line simply removes the progress of a ``make`` process if it fails.
.. code-block:: Makefile .. code-block:: Makefile
.DELETE_ON_ERROR: .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 . 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. 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. 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.
3. The ``image.tar`` is built below this, the cross-compiled ``hello-world`` source code, and ``manifest`` at the bottom. 5. 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>`. For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
Service Config Specification and Rules 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: 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:
@@ -482,14 +485,14 @@ In our example, there is *no need* for a ``config_rules`` file. This is because
Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config. Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config.
Properties 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). 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*** .. ***STATS.YAML IS APPARENTLY BEING DEPRECATED, THIS SECTION NEEDS COMMENT*** Possibly this is not actually the case?
Instructions 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. 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.
@@ -498,12 +501,12 @@ Instructions are the basic directions or any particular details that you would l
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. 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 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. 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 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. 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.

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

@@ -4,85 +4,84 @@
Linux Linux
===== =====
Debian / Ubuntu .. tabs::
---------------
For Debian and Debian-based systems, such as Mint, PopOS etc. .. group-tab:: Debian / Ubuntu
.. note:: The following install is for the LTS (Long Term Support) version of Tor from Debian. If you would like the latest stable release, The Tor Project maintain their own Debian repository. The instructions to connect to this can be found `here <https://support.torproject.org/apt/tor-deb-repo/>`_. 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: .. note:: The following install is for the LTS (Long Term Support) version of Tor from Debian. If you would like the latest stable release, The Tor Project maintain their own Debian repository. The instructions to connect to this can be found `here <https://support.torproject.org/apt/tor-deb-repo/>`_.
.. code-block:: bash Install the Tor proxy service to your system. To do so, open your terminal and run the following command:
sudo apt update && sudo apt install tor .. code-block:: bash
.. tip:: You can check that Tor is running with: sudo apt update && sudo apt install tor
.. code-block:: bash .. tip:: You can check that Tor is running with:
systemctl status tor .. code-block:: bash
In the rare event that Tor is having connectivity issues, you can reset your connection with: systemctl status tor
.. code-block:: bash In the rare event that Tor is having connectivity issues, you can reset your connection with:
sudo systemctl restart tor .. code-block:: bash
Arch / Manjaro sudo systemctl restart tor
--------------
Simply install Tor with: .. group-tab:: Arch / Manjaro
.. code-block:: bash Simply install Tor with:
sudo pacman -S tor .. code-block:: bash
sudo pacman -S tor
.. tip:: You can check that Tor is running with: .. tip:: You can check that Tor is running with:
.. code-block:: bash .. code-block:: bash
systemctl status tor systemctl status tor
In the rare event that Tor is having connectivity issues, you can reset your connection with: In the rare event that Tor is having connectivity issues, you can reset your connection with:
.. code-block:: bash .. code-block:: bash
sudo systemctl restart tor sudo systemctl restart tor
CentOS / Fedora / RHEL .. group-tab:: CentOS / RHEL / Fedora
----------------------
1. Configure the Tor Package repository. Add the following to ``/etc/yum.repos.d/tor.repo``: #. Configure the Tor Package repository. Add the following to ``/etc/yum.repos.d/tor.repo``:
- CentOS / RHEL: - CentOS / RHEL:
.. code-block:: bash .. code-block:: bash
[Tor] [Tor]
name=Tor for Enterprise Linux $releasever - $basearch name=Tor for Enterprise Linux $releasever - $basearch
baseurl=https://rpm.torproject.org/centos/$releasever/$basearch baseurl=https://rpm.torproject.org/centos/$releasever/$basearch
enabled=1 enabled=1
gpgcheck=1 gpgcheck=1
gpgkey=https://rpm.torproject.org/centos/public_gpg.key gpgkey=https://rpm.torproject.org/centos/public_gpg.key
cost=100 cost=100
- Fedora: - Fedora:
.. code-block:: bash .. code-block:: bash
[Tor] [Tor]
name=Tor for Fedora $releasever - $basearch name=Tor for Fedora $releasever - $basearch
baseurl=https://rpm.torproject.org/fedora/$releasever/$basearch baseurl=https://rpm.torproject.org/fedora/$releasever/$basearch
enabled=1 enabled=1
gpgcheck=1 gpgcheck=1
gpgkey=https://rpm.torproject.org/fedora/public_gpg.key gpgkey=https://rpm.torproject.org/fedora/public_gpg.key
cost=100 cost=100
2. Then install the Tor package: #. Then install the Tor package:
.. code-block:: bash .. code-block:: bash
sudo dnf install tor sudo dnf install tor