Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-04-01 21:13:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

restructure docs

Browse Source
This commit is contained in:
Matt Hill
2023-11-06 12:34:37 -07:00
parent 80651a6609
commit fe79d71e7c
150 changed files with 404 additions and 1866 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
site/source/user-manual/alt-registries.rst
View File

@@ -31,6 +31,6 @@ Click "Add custom registry" and enter the URL of your desired Marketplace. You m
Hosting a Registry
------------------
You can run your own basic registry using your Start9 server! On each service's GitHub Releases page, such as `Bitcoin <https://github.com/Start9Labs/bitcoind-wrapper/releases/tag/v23.0.0>`_ for example, you will find the ``.s9pk`` Asset. You can download this package, upload to a folder on `File Browser <https://marketplace.start9.com/marketplace/filebrowser>`_ or `Nextcloud <https://marketplace.start9.com/marketplace/nextcloud>`_, and then host it over :ref:`Tor<tor>` using `Start9 Pages <https://marketplace.start9.com/marketplace/embassy-pages>`_!
You can run your own basic registry using your Start9 server! On each service's GitHub Releases page, such as `Bitcoin <https://github.com/Start9Labs/bitcoind-wrapper/releases/tag/v23.0.0>`_ for example, you will find the ``.s9pk`` Asset. You can download this package, upload to a folder on `File Browser <https://marketplace.start9.com/marketplace/filebrowser>`_ or `Nextcloud <https://marketplace.start9.com/marketplace/nextcloud>`_, and then host it over Tor using `Start9 Pages <https://marketplace.start9.com/marketplace/embassy-pages>`_!
If you are interested in building and hosting your own full registry that can be accessed in the Start9 Marketplace UI, you can check out the `registry repository <github.com/start9labs/registry>`_.

29
site/source/user-manual/backups/index.rst
View File

@@ -6,37 +6,8 @@ Backups
In addition to the safe-keeping of a good master password, maintaining good backups is the major responsibility required to keep the benefits and freedom that come with self-hosting.
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Backup Create
:link: backup-create
:icon: scylla-icon scylla-icon--cloud
:class: large-5
:anchor: Backup
Create an encrypted backup of your server data.
.. topic-box::
:title: Backup Restore
:link: backup-restore
:icon: scylla-icon scylla-icon--live-test
:class: large-5
:anchor: Restore
Restore your server data from a previous backup.
.. raw:: html
</div></div>
.. toctree::
:maxdepth: 1
:hidden:
backup-create
backup-restore

4
site/source/user-manual/change-password.rst
View File

@@ -4,9 +4,9 @@
Password Change
===============
This guide is for changing your password from the web-UI. If you forgot your password and want to reset it, see the :ref:`reset password guide<reset-password>`.
This guide is for changing your password from the main StartOS UI. If you forgot your password and want to reset it, see the :ref:`reset password guide<reset-password>`.
#. Login to the web-UI and navigate to System > Change Master Password
#. Navigate to System > Change Master Password
.. figure:: /_static/images/config/password_change_ui-1.png
:width: 60%

52
site/source/user-manual/configuring-ff.rst Normal file
View File

@@ -0,0 +1,52 @@
.. _configuring-ff:
===================
Configuring Firefox
===================
Firefox is a privacy-focused browser that can be configured to resolve LAN (`.local`) URLs and Tor (`.onion`) URLs without affecting normal browser functionality. We highly recommend using Firefox for connecting to your server and its installed services.
.. note:: For iOS, we recommend Safari instead of Firefox. That is because on iOS, all browsers use Safari under the hood anyway, so it is preferable not to stack unnecessary software on top of it.
Select your OS:
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Linux
:link: ../../../../device-guides/linux/ff-linux
:icon: scylla-icon scylla-icon--linux
:class: large-4
:anchor: View
Configuring Firefox on Linux
.. topic-box::
:title: Mac
:link: ../../../../device-guides/mac/ff-mac
:icon: scylla-icon scylla-icon--apple
:class: large-4
:anchor: View
Configuring Firefox on Mac
.. topic-box::
:title: Windows
:link: ../../../../device-guides/windows/ff-windows
:icon: scylla-icon scylla-icon--windows
:class: large-4
:anchor: View
Configuring Firefox on Windows
.. topic-box::
:title: Android
:link: ../../../../device-guides/android/ff-android
:icon: scylla-icon scylla-icon--android
:class: large-4
:anchor: View
Configuring Firefox on Android

20
site/source/user-manual/connecting-lan.rst Normal file
View File

@@ -0,0 +1,20 @@
.. _connecting-lan:
==================
Connecting Locally
==================
When connected to the same Local Area Network (LAN) as your server, you can use its `.local` URLs for fast and secure connections.
All clients
-----------
#. Ensure your client device (phone/laptop) is connected to the same Local Area Network (LAN) as your server. This usually means your server and your client device are using the same router, either by ethernet or WiFi
#. Follow instructions to :ref:`trust your server's Root CA<trust-ca>`
Windows Only
------------
On Windows, it is currently necessary to install Bonjour Print Services in order to access the `.local` URLs of your installed services. With the release of StartOS v0.4.0, it will no longer be necessary.
#. Simply install Bonjour Print Services from Apple: https://support.apple.com/kb/DL999
.. warning:: Bonjour can be unreliable. If your `local` URLs suddenly stop working, you may need to uninstall and re-install Bonjour. Go to `System Settings > Remove Programs`, uninstall Bonjour `and` Bonjour Print Services, re-install Bonjour Print Services from the link above, then restart Windows.

78
site/source/user-manual/connecting-tor.rst Normal file
View File

@@ -0,0 +1,78 @@
.. _connecting-tor:
===================
Connecting Remotely
===================
You can connect to your server from anywhere in the world, privately and anonymously, by using its unique Tor Address (`.onion` URL)
.. note:: It is normal for Tor connections to be slow or unreliable at times
Running Tor on Your Phone/Computer (Recommended)
------------------------------------------------
Select your OS below:
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Linux
:link: ../../../../device-guides/linux/tor-linux
:icon: scylla-icon scylla-icon--linux
:class: large-4
:anchor: View
Running Tor on Linux
.. topic-box::
:title: Mac
:link: ../../../../device-guides/mac/tor-mac
:icon: scylla-icon scylla-icon--apple
:class: large-4
:anchor: View
Running Tor on Mac
.. topic-box::
:title: Windows
:link: ../../../../device-guides/windows/tor-windows
:icon: scylla-icon scylla-icon--windows
:class: large-4
:anchor: View
Running Tor on Windows
.. topic-box::
:title: Android
:link: ../../../../device-guides/android/tor-android
:icon: scylla-icon scylla-icon--android
:class: large-4
:anchor: View
Running Tor on Android
.. topic-box::
:title: iOS
:link: ../../../../device-guides/ios/tor-ios
:icon: scylla-icon scylla-icon--ios
:class: large-4
:anchor: View
Running Tor on iOS
Using a Tor Browser
-------------------
Using the official Tor Browser allows you to access `.onion` URLs without additional configuration. However, accessing clearnet (`.com`, `.org`, ect) websites will also be routed over Tor, making them slower, and `.local` URLs cannot be accessed at all.
Linux, Mac, Windows, Android
............................
`Download Tor Browser <https://torproject.org/download/>`_
iOS
...
iOS lacks a well-functioning Tor Browser.

7
site/source/user-manual/index.rst
View File

@@ -6,8 +6,13 @@ User Manual
.. toctree::
:includehidden:
:maxdepth: 1
:maxdepth: 2
initial-setup
trust-ca
configuring-ff
connecting-lan
connecting-tor
dashboard-overview
change-password
managing-services

76
site/source/user-manual/initial-setup.rst Normal file
View File

@@ -0,0 +1,76 @@
.. _initial-setup:
=============
Initial Setup
=============
Follow the instructions below to set up your server for the first time.
#. Connect your server to power and Ethernet
#. From a client device (desktop/laptop/phone), open a browser and visit ``http://start.local``. Your client must be connected to the same Local Area Network (LAN) as your server. This usually means they are using the same router, either by ethernet or WiFi
.. note:: If you are `not` using a Raspberry Pi, you can also plug a monitor and keyboard into the server.
#. Select ``Start Fresh``
.. figure:: /_static/images/setup/screen0-startfresh_or_recover.jpg
:width: 50%
:alt: Fresh Setup
#. Select your storage drive. In most cases, there will be only one
.. figure:: /_static/images/setup/screen2-select_storage.jpg
:width: 50%
:alt: Select Drive
#. Create a master password for your server and click ``Finish``
.. warning:: Choose a strong master password. Write it down. Store it somewhere safe. DO NOT LOSE IT.
.. figure:: /_static/images/setup/screen5-set_password_complete.jpg
:width: 50%
:alt: Create New Password
#. StartOS will initialize. This can take a few minutes
.. figure:: /_static/images/setup/screen6-storage_initialize.jpg
:width: 50%
:alt: SSD Initialization
#. Click the ``Download`` button to download a file containing the URLs (`.local` and `.onion`) and Root CA of your server. Keep this file for future reference.
.. note:: If you connected a monitor, you will `not` see the download button
.. figure:: /_static/images/setup/screen7-startfresh_complete.jpg
:width: 50%
:alt: Setup Complete
#. Setup complete! Click ``Login to StartOS`` to access your new server
.. figure:: /_static/images/setup/screen9-startfresh_complete_saved.jpg
:width: 50%
:alt: Setup Complete
#. Now you will need to :ref:`trust your root CA<trust-root-ca-on-initial-setup>` in order to login.
.. _setup-troubleshooting:
Troubleshooting
---------------
If you are experiencing issues with setup, try the following:
#. Confirm that the server is plugged into both power `and` Ethernet
#. Confirm your phone/computer is `not` connected to a "Guest" network
#. Confirm your phone/computer is not using a VPN, or that if you are, that it allows LAN connections, such as the examples below:
- Mullvad - Go to "Settings -> VPN Settings -> Local Network Sharing"
- ProtonVPN - Go to "Preferences -> Connection -> Allow LAN Connections"
#. Visit or refresh (ctrl+shift+R on Linux/Windows, cmd+shift+R on macOS Firefox, cmd+option+E then cmd+R on macOS Safari) the start.local page in a web browser
#. To avoid networking issues, it is recommended to use your `primary` router, not an extender or mesh router
#. Very rarely, your firewall settings may block mDNS. In this case:
- From your browser, navigate to your router configuration settings. This is usually an IP address such as 192.168.1.1. A simple web search will usually reveal how to access the router configuration settings for a particular brand.
- Once in the router config settings, find the section that lists the devices on your network. You should see a device labeled ``start``. Take note of the associated IP address and enter it into your browser's URL field to enter the setup.
You can always to `reach out to support <https://start9.com/contact>`_ if you need a hand.

6
site/source/user-manual/managing-services.rst
View File

@@ -24,9 +24,9 @@ The Service Dashboard provides quick insight into the status and health of your
* **Stopped**: Service is installed and configured, but not currently running.
* **Starting**: Service is in the process of starting up.
* **Running**: Service is running.
* **Launch UI**: If the service offer a User Interface (UI), and the UI is currently available, clicking this button will launch the UI in a new browser tab. Learn more about :ref:`Web UIs<web-ui>`.
* **Health Checks**: This is a critical feature of StartOS. Health Checks are configured by the service packager in order to quickly convey to the user what is happening with their service, as well as possible actions they may want to take. Learn more about :ref:`Health Checks <health-checks>`.
* **Dependencies**: Some services depend on the presence and proper configuration of other services to function. This section will inform you if all dependencies are satisfied and, if not, what to do about it. Learn more about :ref:`Dependencies <service-dependencies>`.
* **Launch UI**: If the service offer a User Interface (UI), and the UI is currently available, clicking this button will launch the UI in a new browser tab.
* **Health Checks**: This is a critical feature of StartOS. Health Checks are configured by the service packager in order to quickly convey to the user what is happening with their service, as well as possible actions they may want to take.
* **Dependencies**: Some services depend on the presence and proper configuration of other services to function. This section will inform you if all dependencies are satisfied and, if not, what to do about it.
* **Start / Stop**: Self-explanatory, use these buttons to start or stop a service.
Installing a Service

2
site/source/user-manual/sessions.rst
View File

@@ -4,7 +4,7 @@
Session Management
==================
Every time a login is made with StartOS, such as from a web browser on your laptop or mobile device, a :ref:`Session <sessions>` is created.
Every time a login is made with StartOS, such as from a web browser on your laptop or mobile device, an authenticated session is created.
* To view and manage your active sessions, go to *System > Active Sessions*.

110
site/source/user-manual/trust-ca.rst Normal file
View File

@@ -0,0 +1,110 @@
.. _trust-ca:
=====================
Trusting Your Root CA
=====================
Download and trust your server's Root Certificate Authority (Root CA) to enable encrypted communications locally and enhance speeds over Tor.
.. _trust-root-ca-on-initial-setup:
Trust Root CA on Initial Setup
------------------------------
If you've just completed initial setup, you will automatically be prompted to trust your server's Root CA. Do these mandatory steps below:
#. Click `DOWNLOAD`` to download your Root CA
.. figure:: /_static/images/setup/trust-ca-1.png
:width: 40%
:alt: Download your Server's Root CA
#. You may see a dialog box noting it saved to your Downloads folder. Select :ref:`VIEW DOCS<trust-your-root-ca>` to learn how to trust your server's Root CA on your device's operating system.
.. figure:: /_static/images/setup/trust-ca-2.png
:width: 40%
:alt:
#. The `Go To Login` panel will display "Waiting for trust..." until you have completed the process to install and trust your Root CA on your device.
.. figure:: /_static/images/setup/trust-ca-3.png
:width: 40%
:alt:
#. Once you've successfully trusted your Root CA, you can login by selecting `OPEN`.
.. figure:: /_static/images/setup/trust-ca-4.png
:width: 40%
:alt:
.. _download-root-ca:
Download Root CA
-----------------
Your server's Root CA was included in the downloaded file at the end of initial setup. If you do not have that file, you can find your server's Root CA inside the StartOS dashboard.
#. Navigate to `System > Root CA` and click `Download Certificate`
.. figure:: /_static/images/ssl/lan_setup.png
:width: 40%
:alt: LAN setup menu item
.. _trust-your-root-ca:
Trust Root CA
--------------
Select your operating system:
.. raw:: html
<div class="topics-grid grid-container full">
<div class="grid-x grid-margin-x">
.. topic-box::
:title: Linux
:link: ../../../../device-guides/linux/ca-linux/
:icon: scylla-icon scylla-icon--linux
:class: large-4
:anchor: View
Trust your Root CA on Linux
.. topic-box::
:title: Mac
:link: ../../../../device-guides/mac/ca-mac
:icon: scylla-icon scylla-icon--apple
:class: large-4
:anchor: View
Trust your Root CA on Mac
.. topic-box::
:title: Windows
:link: ../../../../device-guides/windows/ca-windows
:icon: scylla-icon scylla-icon--windows
:class: large-4
:anchor: View
Trust your Root CA on Windows
.. topic-box::
:title: Android
:link: ../../../../device-guides/android/ca-android
:icon: scylla-icon scylla-icon--android
:class: large-4
:anchor: View
Trust your Root CA on Android
.. topic-box::
:title: iOS
:link: ../../../../device-guides/ios/ca-ios
:icon: scylla-icon scylla-icon--ios
:class: large-4
:anchor: View
Trust your Root CA on iOS