From 8bf90fef45cf268809ee4a365f7c58609289ff8f Mon Sep 17 00:00:00 2001
From: Varac <varac@varac.net>
Date: Tue, 17 Aug 2021 00:18:57 +0200
Subject: [PATCH] Seperate cluster and OAS installation docs
Closes: #924
---
docs/README.md | 2 +-
docs/advanced_installation.rst | 96 -------
docs/conf.py | 3 +-
docs/index.rst | 14 +-
docs/installation.rst | 407 ---------------------------
docs/installation/create_cluster.rst | 237 ++++++++++++++++
docs/installation/install_oas.rst | 215 ++++++++++++++
docs/installation/overview.rst | 105 +++++++
docs/testing.rst | 2 +-
docs/upgrading.rst | 2 +-
docs/usage.rst | 4 +-
11 files changed, 573 insertions(+), 514 deletions(-)
delete mode 100644 docs/advanced_installation.rst
delete mode 100644 docs/installation.rst
create mode 100644 docs/installation/create_cluster.rst
create mode 100644 docs/installation/install_oas.rst
create mode 100644 docs/installation/overview.rst
diff --git a/docs/README.md b/docs/README.md
index 75703f960..b37ad63e3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,7 @@ This folder contains the documentation. You can find the documentation at
https://openappstack.readthedocs.io/. It is also possible to build the
documentation, using Sphinx:
- pip install sphinx recommonmark sphinx_rtd_theme
+ pip install sphinx recommonmark sphinx_rtd_theme sphinx_design
make html
Then point your browser to the newly generated pages:
diff --git a/docs/advanced_installation.rst b/docs/advanced_installation.rst
deleted file mode 100644
index 6db90a4fd..000000000
--- a/docs/advanced_installation.rst
+++ /dev/null
@@ -1,96 +0,0 @@
-=====================
-Advanced installation
-=====================
-
-.. _setup-with-greenhost-api:
-
-Advanced cluster creation: Setup with the Greenhost API
--------------------------------------------------------
-
-- Before you can start, you need to have an API key with Customer
- rights.
-
- 1. In the Cosmos service centre, click your webmaster account name on
- the top right corner
- 2. Go to "User settings"
- 3. Click "API keys"
- 4. Click "New API key"
- 5. Click "Generate new key"
- 6. Give the key "Customer", "CloudCustomer" or "API" access rights. You
- will need "Customer" rights if you want to automatically generate DNS
- rules. If you do not have this right, you have to `manually set the
- right DNS rules <#dns-entries>`__
- later.
- 7. Copy the generated key and run export it to this variable in a
- terminal:
-
- ::
-
- $ export COSMOS_API_TOKEN=<paste your API key here>
-
- 8. In *the same terminal*, you can now use the ``create`` subcommand
-
-- There are two ways to let the installation program know which VPS to use:
-
- 1. Based on an already existing `Greenhost <https://greenhost.net>`__
- VPS, using the ``--droplet-id`` argument.
-
- Find the ID of your VPS either in the Greenhost Cosmos interface (it is
- the numeric part of the URL in the "Manage VPS" screen).
-
- 2. By creating a new VPS through the API, using the ``--create-droplet``
- argument.
-
- In that case, make sure to also provide the ``--create-hostname`` and
- ``--ssh-key-id`` arguments.
-
- You can find your SSH key ID by going to VPS Cloud -> SSH keys and
- checking the link under "Show key". The numerical part is your SSH
- key ID.
-
- *Note: You can also use the API to list ssh keys and find it there.
- Read the `Greenhost API
- documentation <https://service.greenhost.net/cloud/ApiDoc#/default>`__
- for more information*
-
-- In both cases you need to provide the ``DOMAIN_NAME`` positional
- argument.
-
- If you use a subdomain (e.g. ``oas.yourdomain.com``), use the
- ``--subdomain`` command as follows:
-
- ::
-
- $ python -m openappstack oas.example.org create --subdomain oas example.org
-
-- Here is an example of a complete creation command:
-
- ::
-
- $ python -m openappstack oas.example.org create \
- --create-droplet \
- --create-hostname oas.example.org \
- --ssh-key-id 112 \
- --create-domain-records \
- --subdomain oas \
- example.org
-
- Let's break down the arguments:
-
- - ``--create-droplet``: Use the Greenhost API to create a new VPS
- - ``--create-hostname oas.example.org``: Create a VPS with hostname ``oas.example.org``
- - ``--ssh-key-id 112``: Use SSH key ID 112 (you can find your SSH key ID in
- the `Cosmos Service Centre <https://service.greenhost.net>`__ under *VPS Cloud* -> *Installation SSH Keys*. Hover over a button there to see the ID in the URL it uses.
- - ``--create-domain-records``: Use the Greenhost API to create DNS records
- If you do this, you can skip :ref:`step-2`. The following records are
- created:
-
- - An ``A`` record ``oas.example.org`` pointing to the VPSs IP address
- - A ``CNAME`` record ``*.oas.example.org`` pointing to ``oas.example.org``.
-
- - ``--subdomain oas``: Only needed when you use ``--create-domain-records`` so
- the Greenhost API can find your domain. Instead of using positional argument
- ``oas.example.org`` you need to provide
-
-You can now continue to :ref:`step-2`, or :ref:`step-3` if you used the API to
-create the DNS records.
diff --git a/docs/conf.py b/docs/conf.py
index 6866ac98c..519ad5ae2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -32,7 +32,8 @@ with open('../VERSION') as version_file:
# ones.
extensions = [
'recommonmark',
- 'sphinx.ext.autosectionlabel'
+ 'sphinx.ext.autosectionlabel',
+ 'sphinx_design'
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/index.rst b/docs/index.rst
index d44e31085..309c7d1d1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,16 +24,22 @@ For more information, go to `the OpenAppStack website`_.
.. toctree::
:maxdepth: 2
- :caption: First steps
+ :caption: Installation
+
+ installation/overview
+ installation/create_cluster
+ installation/install_oas
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Usage
- installation
usage
testing
- advanced_installation
.. toctree::
:maxdepth: 2
- :caption: Maintenance
+ :caption: Administration
maintenance
upgrading
diff --git a/docs/installation.rst b/docs/installation.rst
deleted file mode 100644
index ee5dfd795..000000000
--- a/docs/installation.rst
+++ /dev/null
@@ -1,407 +0,0 @@
-Installation
-============
-
-This document describes how you can install OpenAppStack on a VPS. The
-installation process will set up a "Kubernetes cluster" which runs
-several open source applications. More information about the
-applications can be found on the `OpenAppStack
-website <https://openappstack.net/>`__.
-
-We will set up a "single-node" OpenAppStack cluster. This means
-everything runs on the same VPS. Support for "multi-node" clusters (a
-Kubernetes cluster on more than one VPS) will come in the future.
-
-.. note::
- All commands in these installation instructions need to be
- run on a trusted provisioning machine (i.e., your laptop) that is
- *not* the VPS that will run OpenAppStack. The installation process
- will generate some secrets that will be saved to this machine.
-
-If you encounter any difficulties while following these instructions,
-please `let us know following our contact
-guide <https://openappstack.net/contact.html>`__.
-
-.. warning::
- - OpenAppStack is still under heavy development and is not ready for
- production use! We anticipate major changes and do not guarantee a
- data-preserving upgrade path from current installations. However, we
- encourage you to try OpenAppStack and ask you to `report all issues
- you encounter <https://openappstack.net/contact.html>`__.
- - When you install OpenAppStack on a server, the installation process
- will make some substantial changes to the server's configuration, so
- please do not use a server that functions as anything other than a
- testing ground.
-
-
-Prerequisites
--------------
-
-During these instructions, you are asked to create a VPS, or have a
-bare metal server ready. The server should meet these requirements:
-
-- Current Debian stable "buster"
-- A public IP address
-- The ability to create DNS records for this IP
-- 6 cores and 12 GB of RAM
-- At least 25GB of disk space for installation, plus more for
- application data. We recommend starting with 30GB.
-- Root ssh access
-- ``python3`` installed (``apt install python3``)
-
-You should also have a trusted machine to run the installer on (we call this the
-``provisioning machine``). All the commands listed in these instructions should
-be run on the provisioning machine, unless specified otherwise:
-
-- You need Python 3 with its development files, Pip and Git installed
- (``apt install python3-pip python3-dev git`` on Debian)
-- ``ssh-agent`` to give you access to your VPS
-- ``kubectl`` (`installation instructions <https://kubernetes.io/docs/tasks/tools/#kubectl>`__)
-- ``flux version 0.14.2`` Download from: https://github.com/fluxcd/flux2/releases/download/v0.14.2/flux_0.14.2_linux_amd64.tar.gz
-
-- We recommend using a `python
- virtualenv <https://docs.python.org/3/tutorial/venv.html>`__ to make
- sure we do not change any of your other projects. Install virtualenv
- by running ``pip3 install --user venv`` or
- ``apt install python3-venv``
-
-Getting the installation script
--------------------------------
-
-On your **provisioning machine**, clone the OpenAppStack git repository
-and checkout the latest release branch (currently ``v0.6``):
-
-::
-
- $ git clone -b v0.6 https://open.greenhost.net/openappstack/openappstack.git
- $ cd openappstack
-
-Create a python virtual environment called "env" that uses python 3.
-This makes sure we do not change any of your other python projects. The
-second command "activates" the virtualenv.
-
-.. note::
- Activating the virtualenv means you will use that environment to install and
- run python programs instead of your global environment. If you close your
- terminal or open a new one, you need to activate the virtualenv again.
-
-::
-
- $ python3 -m venv env
- $ . env/bin/activate
-
-Next, install the OpenAppStack CLI client by running the following
-commands:
-
-::
-
- $ pip3 install -r requirements.txt
-
-Now you can run the OpenAppStack CLI as follows:
-
-::
-
- $ python -m openappstack CLUSTER_NAME <command>
-
-The CLI *always* needs a ``CLUSTER_NAME`` argument. Even for getting
-subcommand help messages. Be sure to run this command in the root
-directory of the git repository. In this tutorial, we're using
-``oas.example.org`` as the cluster name. Try it out by running
-
-::
-
- $ python -m openappstack oas.example.org --help
-
-Install OpenAppStack
---------------------
-
-Setting up OpenAppStack happens in five steps:
-
-1. :ref:`step-1`
-
- Create configuration files.
-
-2. :ref:`step-2`
-
- Configure an A-record for your domain as well as a wild card for the
- applications hosted on subdomains.
-
-3. :ref:`step-3`
-
- Configure settings for application installations.
-
- Optionally configure outgoing email and/or automated backup settings.
-
-4. :ref:`step-4`
-
- Setup the VPS for OpenAppStack and install k3s, lightweight Kubernetes.
-
-5. :ref:`step-5`
-
- Install the OpenAppStack core applications as well as optional applications.
-
-6. :ref:`step-6`
-
- This runs a test in the browser to validate that the installation was
- successful.
-
-.. _step-1:
-
-Step 1: Set up cluster
-~~~~~~~~~~~~~~~~~~~~~~
-
-In this guide, we will setup a cluster with IP address ``1.2.3.4`` on domain
-``oas.example.org``. Substitute these two variables with your IP address and
-your domain.
-
-To set up your cluster, use the ``create`` subcommand of the
-OpenAppStack CLI. First, choose a name (we chose ``oas.example.org``) for
-your cluster. Then run the following command to get information about
-the ``create`` subcommand:
-
-::
-
- $ python -m openappstack oas.example.org create --help
-
-If you want the installation script to automatically create a VPS for you, check
-:ref:`setup-with-greenhost-api`.
-Otherwise, continue here.
-
-If you want to install OpenAppStack on a non-Greenhost VPS, we assume
-you already have a machine with a world-facing IP address. Make sure
-that your VPS meets our `prerequisites <#prerequisites>`__. You'll need
-its *hostname* and its *IP address*.
-
-Create the initial OpenAppStack configuration for your VPS by running the
-following command:
-
-::
-
- $ python -m openappstack oas.example.org create \
- oas.example.org \
- --ip-address 1.2.3.4
-
-This configures your cluster under the fully qualified domain name (FQDN)
-``oas.example.org``, To break down the command:
-
-- the first, positional argument ``oas.example.org`` tells the cluster the domain
- it will be hosted on. This should be a (subdomain of a) domain you own.
-- ``--ip-address 1.2.3.4`` tells the script the IP address of your VPS. This
- will be used to find the VPS during the installation procedure.
-
-The configuration has now been written to the ``clusters/oas.example.org`` on
-your provisioning machine.
-
-.. _step-2:
-
-Step 2: Configure DNS
-~~~~~~~~~~~~~~~~~~~~~
-
-Next, make sure that you have two DNS records that point to your
-cluster. Create these two DNS records:
-
-- An ``A`` record ``oas.example.org`` pointing to the VPS's IP address,
-- A ``CNAME`` record ``*.oas.example.org`` pointing to ``oas.example.org``.
-
-.. Note::
- It is also possible to host OpenAppStack on a domain (with
- no dedicated subdomain). That does imply that the included WordPress site
- will be hosted on your root domain ``example.org``. In that case, make these
- DNS records instead:
-
- - An ``A`` record ``example.org`` pointing to the VPS's IP address,
- - A ``CNAME`` record ``*.example.org`` pointing to ``example.org``.
-
-OpenAppStack will fetch https certificates with `Let's
-Encrypt <https://letsencrypt.org>`__ by default. In order to do this DNS
-entries need to be created.
-
-.. _step-3:
-
-Step 3: Additional configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Copy the file ``install/.flux.env.example`` to your cluster dir
-``clusters/oas.example.org/.flux.env``. This file contains the last bit of
-information you need to configure. You **have to** configure the following
-values. The rest are optional.
-
-- ``ip_address``: The IP address of your cluster
-- ``domain``: The FQDN of your cluster
-- ``admin_email``: a valid email address for the system administrator of your
- cluster.
-
-Outgoing email
-''''''''''''''
-
-If you want apps like Nextcloud, RocketChat and Prometheus to be able to send
-email notifications, you need to provide an email account.
-
-.. Note::
- OpenAppStack does not set up an email server for you. In order to enable
- outgoing emails you need to provide an already existing email account.
-
-OpenAppStack uses SMTP to send emails. Search your email provider's helpdesk
-for SMTP configuration details and enter them in the
-``clusters/oas.example.org/.flux.env`` file as follows:
-
-.. code::
-
- # Enable sending mails
- outgoing_mail_enabled=true
- # Email address that the cluster sends mails from. Needs to be an existing SMTP
- # login
- outgoing_mail_from_address=admin@example.org
- # Same outgoing mail address, but only the part before the '@'
- outgoing_mail_from_local_part=admin
- # Same outgoing mail address, but only the part after the '@'
- outgoing_mail_domain=example.org
- # SMTP password for the outgoing mail address
- outgoing_mail_smtp_password=CHANGEME
- # SMTP username, often the same as the outgoing email address
- outgoing_mail_smtp_user=admin@example.org
- # SMTP login data.
- outgoing_mail_smtp_host=smtp.greenhost.nl
- outgoing_mail_smtp_authtype=LOGIN
- outgoing_mail_smtp_port=587
-
-.. _backups-with-velero:
-
-Backups with Velero
-'''''''''''''''''''
-
-You can enable `Velero <https://velero.io>`__, a program that
-runs on your cluster and uploads backups of your cluster and user data to an
-S3 storage service of your choice.
-
-If enabled, Velero will create a backup of your cluster once every night and
-upload it to the S3 storage you configure. This includes:
-
-- your cluster state. Technically speaking, it will back up all Kubernetes
- namespaces in your cluster, except ``velero`` itself; this includes things
- like which applications are installed, including their version number and
- installation-time settings;
-- persistent data of all applications: for example, single sign-on users that
- you created, Nextcloud files and metadata, WordPress site data and comments,
- Rocket.Chat chat history, etc. A single exception to this is Prometheus data
- (statistics of system properties), which takes up a lot of space and we
- consider not valuable enough to back up.
-
-It does not include anything on the VPS that you may have set up but is not
-part of OpenAppStack, like programs installed via ``apt``, or data added to the
-VPS disk not through OpenAppStack.
-
-To configure Velero, edit the file ``clusters/oas.example.org/.flux.env``,
-and configure the settings with the ``backup_s3_`` prefix.
-
-Then continue with the installation procedure as described below. At the end of
-the installation procedure, you have to install the ``velero`` application.
-
-.. _step-4:
-
-Step 4: Setup cluster
-~~~~~~~~~~~~~~~~~~~~~
-
-You're almost ready to start the OpenAppStack installation script.
-First, make sure your DNS configuration is propagated. To do so, make
-sure 'ping' shows your VPS's IP address:
-
-::
-
- $ ping oas.example.org
-
-The ``install`` command will try to log into your machine as the ``root``\ user
-using SSH.
-
-Run the ``install`` command with the CLI to completely configure your VPS for
-OpenAppStack.
-
-::
-
- $ python -m openappstack oas.example.org install
-
-
-This will take a few minutes. It installs k3s, a lightweight Kubernetes. `Flux`_
-is installed to manage applications and keep them updated automatically.
-
-.. _flux: https://fluxcd.io
-
-In the future, we will add commands that show you the status of the
-application installation. For now, just wait half an hour for everything
-to settle, and then continue to the next step (validating your setup).
-
-.. Note::
- It is possible to re-run the ``install`` command with a newer version of the
- installation script. This usually updates k3s and can have other benefits.
-
-.. _step-5:
-
-Step 5: Install applications
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Before you can start, you need to execute a few commands from the installation
-directory **on your provisioning machine**. Don't forget to replace
-``oas.example.org`` with your domain.
-
-.. code:: bash
-
- export CLUSTER_DIR=clusters/oas.example.org
- # Copy the installation kustomization to your cluster directory
- cp install/kustomization.yaml $CLUSTER_DIR/
- # Tell kubectl to use your cluster's kube_config
- export KUBECONFIG=$CLUSTER_DIR/kube_config_cluster.yml
- # This inserts the configuration from .flux.env into your cluster as a "secret"
- kubectl apply -k $CLUSTER_DIR
-
-After you have executed that code, your terminal should show:
-
-.. code:: bash
-
- secret/oas-cluster-variables created
-
-Next, run:
-
-.. code::
-
- ./install/install-openappstack.sh
-
-This installs the *core* of OpenAppStack into your ``k3s`` cluster. To see
-what's included, check the ``flux2/infrastructure`` and the ``flux2/core``
-folders. In addition, it sets up Prometheus and Grafana to monitor your cluster.
-
-After the script completes, you can install applications by running the other
-installation scripts in the ``install`` folder. At the moment, we have scripts
-to install:
-
-- Nextcloud and Onlyoffice with ``./install/install-app.sh nextcloud``
-- Rocket.Chat with ``./install/install-app.sh rocketchat``
-- Wekan with ``./install/install-app.sh wekan``
-- WordPress with ``./install/install-app.sh wordpress``
-- Velero with ``./install/install-app.sh velero`` (only if you have configured it in
- :ref:`backups-with-velero`).
-
-When the installation scripts complete, the application installation may still
-be running on the OpenAppStack cluster. You can monitor the progress by running
-``flux get kustomizations`` (use ``watch flux get kustomizations`` to get
-updates). If all kustomizations have been applied correctly, you can monitor
-specific application releases by running ``watch flux get helmreleases
---all-namespaces``.
-
-.. _step-6:
-
-Step 6: Validate setup
-~~~~~~~~~~~~~~~~~~~~~~
-
-Because OpenAppStack is still under development, we would like you to
-follow our `testing instructions <testing.html>`__ to make sure
-that the setup process went well.
-
-Step 7: Let us know!
-~~~~~~~~~~~~~~~~~~~~
-
-We would love to hear about your experience installing OpenAppStack. If you
-encountered any problems, please create an issue in our `issue tracker
-<https://open.greenhost.net/groups/openappstack/-/issues>`__. If you didn't
-please still reach out as described on our `contact page
-<https://openappstack.net/contact.html>`__ and tell us how you like OpenAppStack
-so far. We want to be in communication with our users, and we want to help you
-if you run into problems.
diff --git a/docs/installation/create_cluster.rst b/docs/installation/create_cluster.rst
new file mode 100644
index 000000000..f87c9b39b
--- /dev/null
+++ b/docs/installation/create_cluster.rst
@@ -0,0 +1,237 @@
+.. _create_kubernetes_cluster:
+
+===========================
+Create a kubernetes cluster
+===========================
+
+This document describes how you can use OpenAppStack to install
+`k3s <https://k3s.io/>`_, a lightweight Kubernetes distribution on a virtual
+private server.
+
+For OpenAppStack we will set up a "single-node" kubernetes cluster. This means
+everything runs on the same VPS. Support for "multi-node" clusters (a
+Kubernetes cluster on more than one VPS) will come in the future.
+
+Prerequisites
+=============
+
+During these instructions, you are asked to create a VPS, or have a
+bare metal server ready. The server should meet these requirements:
+
+- Current Debian stable "buster"
+- A public IP address
+- The ability to create DNS records for this IP
+- 6 cores and 12 GB of RAM
+- At least 25GB of disk space for installation, plus more for
+ application data. We recommend starting with 30GB.
+- Root ssh access
+
+- ``ssh-agent`` to give you access to your VPS
+
+In this guide, we will create a cluster with IP address ``1.2.3.4`` on domain
+``oas.example.org``. Substitute these two variables with your IP address and
+your domain.
+
+.. _create_config:
+
+Step 1: Create cluster configuration
+====================================
+
+To create a config for your cluster, use the ``create`` subcommand of the
+OpenAppStack CLI. First, choose a name (we chose ``oas.example.org``) for
+your cluster. Then run the following command to get information about
+the ``create`` subcommand:
+
+::
+
+ $ python -m openappstack oas.example.org create --help
+
+If you want the installation script to automatically create a VPS for you, check
+:ref:`setup-with-greenhost-api`.
+Otherwise, continue here.
+
+If you want to install OpenAppStack on a non-Greenhost VPS, we assume
+you already have a machine with a world-facing IP address. Make sure
+that your VPS meets our `prerequisites <#prerequisites>`__. You'll need
+its *hostname* and its *IP address*.
+
+Create the initial OpenAppStack configuration for your VPS by running the
+following command:
+
+::
+
+ $ python -m openappstack oas.example.org create \
+ oas.example.org \
+ --ip-address 1.2.3.4
+
+This configures your cluster under the fully qualified domain name (FQDN)
+``oas.example.org``, To break down the command:
+
+- the first, positional argument ``oas.example.org`` tells the cluster the domain
+ it will be hosted on. This should be a (subdomain of a) domain you own.
+- ``--ip-address 1.2.3.4`` tells the script the IP address of your VPS. This
+ will be used to find the VPS during the installation procedure.
+
+The configuration has now been written to the ``clusters/oas.example.org`` on
+your provisioning machine.
+
+.. _configure_dns:
+
+Step 2: Configure DNS
+=====================
+
+Next, make sure that you have two DNS records that point to your
+cluster. Create these two DNS records:
+
+- An ``A`` record ``oas.example.org`` pointing to the VPS's IP address,
+- A ``CNAME`` record ``*.oas.example.org`` pointing to ``oas.example.org``.
+
+.. Note::
+ It is also possible to host OpenAppStack on a domain (with
+ no dedicated subdomain). That does imply that the included WordPress site
+ will be hosted on your root domain ``example.org``. In that case, make these
+ DNS records instead:
+
+ - An ``A`` record ``example.org`` pointing to the VPS's IP address,
+ - A ``CNAME`` record ``*.example.org`` pointing to ``example.org``.
+
+OpenAppStack will fetch https certificates with `Let's
+Encrypt <https://letsencrypt.org>`__ by default. In order to do this DNS
+entries need to be created.
+
+.. _create_cluster:
+
+Step 3: Create cluster
+======================
+
+You're almost ready to start the OpenAppStack installation script.
+First, make sure your DNS configuration is propagated. To do so, make
+sure 'ping' shows your VPS's IP address:
+
+::
+
+ $ ping oas.example.org
+
+The ``install`` command will try to log into your machine as the ``root``\ user
+using SSH.
+
+Run the ``install`` command with the CLI to completely configure your VPS for
+OpenAppStack.
+
+::
+
+ $ python -m openappstack oas.example.org install
+
+
+This will take a few minutes. It installs `link <k3s_>`_, a lightweight
+Kubernetes and useful tools like `kubectl`_ (Kubernetes cli tool), `krew`_
+(a kubectl plugin manager), `flux`_ (used for automated updates) and `velero`_
+(Kubernetes resources and persistent volumes backup) on it.
+
+.. _kubectl: https://kubernetes.io/docs/reference/kubectl/overview
+.. _flux: https://fluxcd.io
+.. _krew: https://krew.sigs.k8s.io
+.. _velero: https://velero.io
+
+.. Note::
+ It is possible to re-run the ``install`` command with a newer version of the
+ installation script. This usually updates k3s and can have other benefits.
+
+Now you have a single-node k3s/Kuberetes cluster running and can continue with
+:ref:`install_oas`.
+
+Advanced installation
+=====================
+
+.. _setup-with-greenhost-api:
+
+Cluster creation with the Greenhost API
+---------------------------------------
+
+- Before you can start, you need to have an API key with Customer
+ rights.
+
+ 1. In the Cosmos service centre, click your webmaster account name on
+ the top right corner
+ 2. Go to "User settings"
+ 3. Click "API keys"
+ 4. Click "New API key"
+ 5. Click "Generate new key"
+ 6. Give the key "Customer", "CloudCustomer" or "API" access rights. You
+ will need "Customer" rights if you want to automatically generate DNS
+ rules. If you do not have this right, you have to `manually set the
+ right DNS rules <#dns-entries>`__
+ later.
+ 7. Copy the generated key and run export it to this variable in a
+ terminal:
+
+ ::
+
+ $ export COSMOS_API_TOKEN=<paste your API key here>
+
+ 8. In *the same terminal*, you can now use the ``create`` subcommand
+
+- There are two ways to let the installation program know which VPS to use:
+
+ 1. Based on an already existing `Greenhost <https://greenhost.net>`__
+ VPS, using the ``--droplet-id`` argument.
+
+ Find the ID of your VPS either in the Greenhost Cosmos interface (it is
+ the numeric part of the URL in the "Manage VPS" screen).
+
+ 2. By creating a new VPS through the API, using the ``--create-droplet``
+ argument.
+
+ In that case, make sure to also provide the ``--create-hostname`` and
+ ``--ssh-key-id`` arguments.
+
+ You can find your SSH key ID by going to VPS Cloud -> SSH keys and
+ checking the link under "Show key". The numerical part is your SSH
+ key ID.
+
+ *Note: You can also use the API to list ssh keys and find it there.
+ Read the `Greenhost API
+ documentation <https://service.greenhost.net/cloud/ApiDoc#/default>`__
+ for more information*
+
+- In both cases you need to provide the ``DOMAIN_NAME`` positional
+ argument.
+
+ If you use a subdomain (e.g. ``oas.yourdomain.com``), use the
+ ``--subdomain`` command as follows:
+
+ ::
+
+ $ python -m openappstack oas.example.org create --subdomain oas example.org
+
+- Here is an example of a complete creation command:
+
+ ::
+
+ $ python -m openappstack oas.example.org create \
+ --create-droplet \
+ --create-hostname oas.example.org \
+ --ssh-key-id 112 \
+ --create-domain-records \
+ --subdomain oas \
+ example.org
+
+ Let's break down the arguments:
+
+ - ``--create-droplet``: Use the Greenhost API to create a new VPS
+ - ``--create-hostname oas.example.org``: Create a VPS with hostname ``oas.example.org``
+ - ``--ssh-key-id 112``: Use SSH key ID 112 (you can find your SSH key ID in
+ the `Cosmos Service Centre <https://service.greenhost.net>`__ under *VPS Cloud* -> *Installation SSH Keys*. Hover over a button there to see the ID in the URL it uses.
+ - ``--create-domain-records``: Use the Greenhost API to create DNS records
+ If you do this, you can skip :ref:`configure_dns`. The following records are
+ created:
+
+ - An ``A`` record ``oas.example.org`` pointing to the VPSs IP address
+ - A ``CNAME`` record ``*.oas.example.org`` pointing to ``oas.example.org``.
+
+ - ``--subdomain oas``: Only needed when you use ``--create-domain-records`` so
+ the Greenhost API can find your domain. Instead of using positional argument
+ ``oas.example.org`` you need to provide
+
+You can now continue to :ref:`configure_dns`, or :ref:`create_cluster` if you used the API to
+create the DNS records.
diff --git a/docs/installation/install_oas.rst b/docs/installation/install_oas.rst
new file mode 100644
index 000000000..4747a7f66
--- /dev/null
+++ b/docs/installation/install_oas.rst
@@ -0,0 +1,215 @@
+.. _install_oas:
+
+====================
+Install OpenAppStack
+====================
+
+This guide explains how to install OpenAppStack either on an existing Kubernetes
+cluster that you have setup entirely yourself, or on a cluster you created
+following the OpenAppStack :ref:`create_cluster` guide.
+Please choose one of the below options:
+
+.. tab-set::
+
+ .. tab-item:: A. Install on cluster created by OpenAppStack cli
+
+ If you followed the :ref:`create_cluster` guide to setup a Kubernetes cluster
+ using the OpenAppStack CLI tool you're all set and can continue with the
+ next step (:ref:`flux_config`).
+
+ .. tab-item:: B. Install on existing cluster
+
+ .. Note::
+ - Installation on an existing Kubernetes cluster ist still experiental and
+ might not work depending on the setup of your cluster/cloud provider.
+ We'll be happy to recieve feedback from your experiences though altough
+ we cannot guarrente !
+
+ **Prerequisites**:
+
+ - A single-node Kubernetes cluster
+ - A ``kube_config.yml`` file for API access
+
+ **Configure DNS**: Please follow :ref:`configure_dns` how to setup the DNS records for OpenAppStack.
+
+ **Setup**:
+
+ - Create a directory containing your cluster configuration, i.e.
+ ``mkdir -p clusters/oas.example.org``
+ - Copy your `kube_config.yml` file inside your cluster config directory and
+ rename it on the way to `` kube_config_cluster.yml``:
+ ``mv kube_config.yml clusters/oas.example.org/kube_config_cluster.yml``
+
+ **Installation**: Please continue with the next step (:ref:`flux_config`).
+
+.. _flux_config:
+
+Flux configuration
+==================
+
+.. _flux_prerequisites:
+
+Prerequisites
+-------------
+
+- ``kubectl`` (`installation instructions <https://kubernetes.io/docs/tasks/tools/#kubectl>`__)
+- ``flux version 0.14.2`` `Download flux_0.14.2_linux_amd64.tar.gz <https://github.com/fluxcd/flux2/releases/download/v0.14.2/flux_0.14.2_linux_amd64.tar.gz>`_
+
+Copy the file ``install/.flux.env.example`` to your cluster dir
+``clusters/oas.example.org/.flux.env``. This file contains the last bit of
+information you need to configure. You **have to** configure the following
+values. The rest are optional.
+
+- ``ip_address``: The IP address of your cluster
+- ``domain``: The FQDN of your cluster
+- ``admin_email``: a valid email address for the system administrator of your
+ cluster.
+
+Outgoing email
+--------------
+
+If you want apps like Nextcloud, RocketChat and Prometheus to be able to send
+email notifications, you need to provide an email account.
+
+.. Note::
+ OpenAppStack does not set up an email server for you. In order to enable
+ outgoing emails you need to provide an already existing email account.
+
+OpenAppStack uses SMTP to send emails. Search your email provider's helpdesk
+for SMTP configuration details and enter them in the
+``clusters/oas.example.org/.flux.env`` file as follows:
+
+.. code::
+
+ # Enable sending mails
+ outgoing_mail_enabled=true
+ # Email address that the cluster sends mails from. Needs to be an existing SMTP
+ # login
+ outgoing_mail_from_address=admin@example.org
+ # Same outgoing mail address, but only the part before the '@'
+ outgoing_mail_from_local_part=admin
+ # Same outgoing mail address, but only the part after the '@'
+ outgoing_mail_domain=example.org
+ # SMTP password for the outgoing mail address
+ outgoing_mail_smtp_password=CHANGEME
+ # SMTP username, often the same as the outgoing email address
+ outgoing_mail_smtp_user=admin@example.org
+ # SMTP login data.
+ outgoing_mail_smtp_host=smtp.greenhost.nl
+ outgoing_mail_smtp_authtype=LOGIN
+ outgoing_mail_smtp_port=587
+
+.. _backups-with-velero:
+
+Backups with Velero
+-------------------
+
+You can enable `Velero <https://velero.io>`__, a program that
+runs on your cluster and uploads backups of your cluster and user data to an
+S3 storage service of your choice.
+
+If enabled, Velero will create a backup of your cluster once every night and
+upload it to the S3 storage you configure. This includes:
+
+- your cluster state. Technically speaking, it will back up all Kubernetes
+ namespaces in your cluster, except ``velero`` itself; this includes things
+ like which applications are installed, including their version number and
+ installation-time settings;
+- persistent data of all applications: for example, single sign-on users that
+ you created, Nextcloud files and metadata, WordPress site data and comments,
+ Rocket.Chat chat history, etc. A single exception to this is Prometheus data
+ (statistics of system properties), which takes up a lot of space and we
+ consider not valuable enough to back up.
+
+It does not include anything on the VPS that you may have set up but is not
+part of OpenAppStack, like programs installed via ``apt``, or data added to the
+VPS disk not through OpenAppStack.
+
+To configure Velero, edit the file ``clusters/oas.example.org/.flux.env``,
+and configure the settings with the ``backup_s3_`` prefix.
+
+Then continue with the installation procedure as described below. At the end of
+the installation procedure, you have to install the ``velero`` application.
+
+
+Step 5: Install core applications
+=================================
+
+Before you can start, you need to execute a few commands from the installation
+directory **on your provisioning machine**. Don't forget to replace
+``oas.example.org`` with your domain.
+
+.. code:: bash
+
+ export CLUSTER_DIR=clusters/oas.example.org
+
+ # Copy the installation kustomization to your cluster directory
+ cp install/kustomization.yaml $CLUSTER_DIR/
+
+ # Tell kubectl to use your cluster's kube_config
+ export KUBECONFIG=$CLUSTER_DIR/kube_config_cluster.yml
+
+ # Ensure flux-system namespace is created
+ kubectl get namespace flux-system || kubectl create namespace flux-system
+
+ # This inserts the configuration from .flux.env into your cluster as a "secret"
+ kubectl apply -k $CLUSTER_DIR
+
+After you have executed that code, your terminal should show:
+
+.. code:: bash
+
+ secret/oas-cluster-variables created
+
+Next, run:
+
+.. code::
+
+ ./install/install-openappstack.sh
+
+This installs the *core* of OpenAppStack into your ``k3s`` cluster. To see
+what's included, check the ``flux2/infrastructure`` and the ``flux2/core``
+folders. In addition, it sets up Prometheus and Grafana to monitor your cluster.
+
+.. _additional_apps:
+
+Install additional applications
+===============================
+
+After the script completes, you can install applications by running the other
+installation scripts in the ``install`` folder. At the moment, we have scripts
+to install:
+
+- Nextcloud and Onlyoffice with ``./install/install-app.sh nextcloud``
+- Rocket.Chat with ``./install/install-app.sh rocketchat``
+- Wekan with ``./install/install-app.sh wekan``
+- WordPress with ``./install/install-app.sh wordpress``
+- Velero with ``./install/install-app.sh velero`` (only if you have configured it in
+ :ref:`backups-with-velero`).
+
+When the installation scripts complete, the application installation may still
+be running on the OpenAppStack cluster. You can monitor the progress by running
+``flux get kustomizations`` (use ``watch flux get kustomizations`` to get
+updates). If all kustomizations have been applied correctly, you can monitor
+specific application releases by running ``watch flux get helmreleases
+--all-namespaces``.
+
+.. _step-6:
+
+Step 6: Validate setup
+======================
+
+Because OpenAppStack is still under development, we would like you to
+follow our `testing instructions <testing.html>`__ to make sure
+that the setup process went well.
+
+Step 7: Let us know!
+====================
+
+We would love to hear about your experience installing OpenAppStack. If you
+encountered any problems, please create an issue in our `issue tracker
+<https://open.greenhost.net/groups/openappstack/-/issues>`__. If you didn't
+please still reach out as described on our `contact page
+<https://openappstack.net/contact.html>`__ and tell us how you like OpenAppStack
+so far. We want to be in communication with our users, and we want to help you
+if you run into problems.
diff --git a/docs/installation/overview.rst b/docs/installation/overview.rst
new file mode 100644
index 000000000..883228ea0
--- /dev/null
+++ b/docs/installation/overview.rst
@@ -0,0 +1,105 @@
+.. _installation_overview:
+
+=====================
+Installation overview
+=====================
+
+.. warning::
+ - OpenAppStack is still under heavy development and is not ready for
+ production use! We anticipate major changes and do not guarantee a
+ data-preserving upgrade path from current installations. However, we
+ encourage you to try OpenAppStack and ask you to `report all issues
+ you encounter <https://openappstack.net/contact.html>`__.
+ - When you install OpenAppStack on a server, the installation process
+ will make some substantial changes to the server's configuration, so
+ please do not use a server that functions as anything other than a
+ testing ground.
+
+ .. note::
+ You should also have a trusted machine to run the installer on, i.e. your
+ laptop. We call this the ``provisioning machine``.
+ All commands in these installation instructions need to be
+ run this provisioning machine that is *not* the server that will run
+ OpenAppStack, unless specified otherwise.
+
+Setup
+=====
+
+Common prerequisites
+--------------------
+
+Wether you want to create a kubernetes cluster first or want to install
+OpenAppStack on an existing cluster, these are the common prerequisites:
+
+- You need Python 3 with its development files, Pip and Git installed
+ (``apt install python3-pip python3-dev git`` on Debian)
+- We recommend using a `python
+ virtualenv <https://docs.python.org/3/tutorial/venv.html>`__ to make
+ sure we do not change any of your other projects. Install virtualenv
+ by running ``pip3 install --user venv`` or ``apt install python3-venv``.
+
+Clone the OpenAppStack git repository
+-------------------------------------
+
+On your **provisioning machine**, clone the OpenAppStack git repository
+and checkout the latest release branch (currently ``v0.6``):
+
+::
+
+ $ git clone -b v0.7 https://open.greenhost.net/openappstack/openappstack.git
+ $ cd openappstack
+
+Create a python virtual environment
+-----------------------------------
+
+Create a python virtual environment called "env" that uses python 3.
+This makes sure we do not change any of your other python projects. The
+second command "activates" the virtualenv.
+
+.. note::
+ Activating the virtualenv means you will use that environment to install and
+ run python programs instead of your global environment. If you close your
+ terminal or open a new one, you need to activate the virtualenv again.
+
+::
+
+ $ python3 -m venv env
+ $ . env/bin/activate
+
+Install requirements
+--------------------
+
+Next, install the OpenAppStack CLI client by running the following
+commands:
+
+::
+
+ $ pip3 install -r requirements.txt
+
+OpenAppStack CLI client usage
+-----------------------------
+
+Now you can run the OpenAppStack CLI as follows:
+
+::
+
+ $ python -m openappstack CLUSTER_NAME <command>
+
+The CLI *always* needs a ``CLUSTER_NAME`` argument. Even for getting
+subcommand help messages. Be sure to run this command in the root
+directory of the git repository. In this tutorial, we're using
+``oas.example.org`` as the cluster name. Try it out by running
+
+::
+
+ $ python -m openappstack oas.example.org --help
+
+
+Installation options
+====================
+
+1. If you want to create a Kubernetes cluster from scratch on a dedicated server
+ or virtual machine please start with :ref:`create_cluster` and
+ then continue with :ref:`install_oas`.
+#. If you want to install Openappstack on an existing Kubernetes cluster you can
+ skip the above instructions and start with :ref:`install_oas`.
diff --git a/docs/testing.rst b/docs/testing.rst
index 2ac2869e3..45d2f150a 100644
--- a/docs/testing.rst
+++ b/docs/testing.rst
@@ -18,7 +18,7 @@ OAS installation
----------------
First we’d like you to setup an OpenAppStack cluster by yourself,
-following the :ref:`installation:Installation` and :ref:`usage:Usage` documentation and make sure
+following the :ref:`installation_overview` and :ref:`usage:Usage` documentation and make sure
you complete all steps.
Command line tests
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index f63b029cf..efe906978 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -159,7 +159,7 @@ A few things are important when upgrading to 0.6.0:
- We now use Flux 2 and the installation procedure has been overhauled. For this
reason we advice you to set up a completely new cluster.
- Copy your configuration details from ``settings.yaml`` to a new ``.flux.env``.
- See ``install/.flux.env.example`` and the :ref:`installation:Installation`
+ See ``install/.flux.env.example`` and the :ref:`installation_overview`
instructions for more information.
Please `reach out to us`_ if you are using, or plan to use OAS in
diff --git a/docs/usage.rst b/docs/usage.rst
index 9e8e3ad4e..de5e6441c 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -24,7 +24,7 @@ them access to applications, take a look at the `user panel documentation
.. note::
If you don't see applications, make sure you have installed at least one
- optional application in :ref:`step-5` of the installation procedure.
+ optional application in :ref:`additional_apps` of the installation procedure.
For creating users follow the `user creation documentation
<https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user>`_.
@@ -132,5 +132,3 @@ WordPress
~~~~~~~~~
`WordPress <https://wordpress.com>`__ is a website content management system.
-Click the ``Log in`` button and then click ``Login with OpenID Connect`` to use
-single sign-on.
--
GitLab