diff --git a/docs/index.rst b/docs/index.rst
index 082dbdae91af60c29b0bbc0986ae42bcfd2eab43..fa8f3ea2648fb70e47fc76e21dfd8dd7352021ff 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -26,7 +26,7 @@ For more information, go to `the Stackspin website`_.
:maxdepth: 2
:caption: Installation
- installation/overview
+ installation/install_cli
installation/create_cluster
installation/install_stackspin
diff --git a/docs/installation/_dns_config.rst b/docs/installation/_dns_config.rst
new file mode 100644
index 0000000000000000000000000000000000000000..dc2de1afab70e68e1cec164c6ae2cf817188fafb
--- /dev/null
+++ b/docs/installation/_dns_config.rst
@@ -0,0 +1,19 @@
+Stackspin secures your connections with https certificates from `Let's Encrypt
+<https://letsencrypt.org>`__. In order to do this, DNS entries need to be
+created before you start the installation.
+
+Stackspin needs two DNS records that point to your cluster. Create these two DNS
+records:
+
+- An ``A`` record ``stackspin.example.org`` pointing to the cluster's IP address,
+- A ``CNAME`` record ``*.stackspin.example.org`` pointing to ``stackspin.example.org``.
+
+.. Note::
+
+ It is also possible to host Stackspin 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``.
diff --git a/docs/installation/_install_on_a_vps.rst b/docs/installation/_install_on_a_vps.rst
new file mode 100644
index 0000000000000000000000000000000000000000..623c8e7fbfe7b5447631f12d9b69354d3e1a3483
--- /dev/null
+++ b/docs/installation/_install_on_a_vps.rst
@@ -0,0 +1,78 @@
+We recommend manually installing Stackspin on a Greenhost VPS as explained
+below. However, if you plan on installing many Stackspin instances, click
+the tab *"ADVANCED: Use the Greenhost API"* to learn how to automatically create
+VPSs and DNS records and install Stackspin on them.
+
+This document describes how you can use Stackspin's CLI to install
+`k3s`_, a lightweight Kubernetes distribution on a virtual
+private server.
+
+For Stackspin 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.
+
+.. tab-set::
+
+ .. tab-item:: Manually install on a VPS
+
+ .. include:: _manual_install.rst
+
+ .. tab-item:: ADVANCED: Use the Greenhost API
+
+ .. include:: _use_greenhost_api.rst
+
+.. _configure_dns:
+
+**Step 2: DNS Configuration**
+
+.. include:: _dns_config.rst
+
+**Step 3: Create Kubernetes cluster**
+
+Before you continue, make sure your DNS configuration is propagated. You
+can do this by making sure ``ping`` shows your VPS's IP address:
+
+.. code:: bash
+
+ $ ping stackspin.example.org
+ # Example output of the command:
+ PING stackspin.example.org (1.2.3.4) 56(84) bytes of data.
+ 64 bytes from 1.2.3.4 (1.2.3.4): icmp_seq=1 ttl=62 time=9.43 ms
+ 64 bytes from 1.2.3.4 (1.2.3.4): icmp_seq=2 ttl=62 time=52.5 ms
+ ...
+
+If you've never logged into this machine before, you might need to accept the
+SSH hostkey before you can start the installation process. To be sure, log into
+your VPS once before you continue:
+
+.. code:: bash
+
+ $ ssh root@stackspin.example.org
+
+If necessary, check your hostkey fingerprint and type ``yes`` to continue. You
+should get a shell on your VPS. Type ``exit`` to quit the shell and continue on
+your provisioning machine.
+
+Run the ``install`` command with the CLI to completely configure your VPS for
+Stackspin.
+
+::
+
+ $ python -m stackspin stackspin.example.org install
+
+
+This will take a few minutes. It tries to connect to your VPS as the root
+user, then installs `k3s`_. In addition it installs command line tools
+`kubectl`_ (Kubernetes cli tool), `flux`_ (used for automated updates) and
+`velero`_ (Kubernetes resources and persistent volumes backup) so you can
+manage the Kubernetes cluster from a shell on the VPS.
+
+.. _kubectl: https://kubernetes.io/docs/reference/kubectl/overview
+.. _flux: https://fluxcd.io
+.. _k3s: https://k3s.io/
+.. _velero: https://velero.io
+
+.. Note::
+ It is possible to re-run the ``install`` command with a newer version
+ of the installation script. Refer to the :ref:`upgrade_guide` for
+ details.
diff --git a/docs/installation/_install_on_existing_cluster.rst b/docs/installation/_install_on_existing_cluster.rst
new file mode 100644
index 0000000000000000000000000000000000000000..74461986c6dd9c226c42919348c9b079e0819ef9
--- /dev/null
+++ b/docs/installation/_install_on_existing_cluster.rst
@@ -0,0 +1,22 @@
+.. 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**
+
+.. include:: _dns_config.rst
+
+**Setup**
+
+- Create a directory containing your cluster configuration, i.e.
+ ``mkdir -p clusters/stackspin.example.org``
+- Copy your ``kube_config.yml`` file inside your cluster config directory
+ and rename it to ``kube_config_cluster.yml``:
+ ``cp kube_config.yml clusters/stackspin.example.org/kube_config_cluster.yml``
diff --git a/docs/installation/_manual_install.rst b/docs/installation/_manual_install.rst
new file mode 100644
index 0000000000000000000000000000000000000000..261cb4052d6e8dd81e7e8333cf05cadd93e6c245
--- /dev/null
+++ b/docs/installation/_manual_install.rst
@@ -0,0 +1,52 @@
+**Prerequisites**
+
+These instructions assume you have a VPS or other kind of server
+ready that meets the following requirements:
+
+- Debian 11 (bullseye) installed
+- 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 at least 30GB.
+- Root ssh access
+
+You'll need the machine's *IP address*.
+
+This guide assumes the VPS's IP address is ``1.2.3.4`` and we
+install on the domain ``stackspin.example.org``. Substitute these
+two variables with your IP address and the (sub)domain you want
+Stackpin to be available on.
+
+.. _create_cluster:
+
+**Step 1: Create cluster configuration**
+
+To create a config for your cluster, use the ``create`` subcommand of the
+Stackspin CLI. First, choose a name (we chose ``stackspin.example.org``) for
+your cluster. Then run the following command to get information about
+the ``create`` subcommand:
+
+::
+
+ $ python -m stackspin stackspin.example.org create --help
+
+Create the initial Stackspin configuration for your VPS by running the
+following command:
+
+::
+
+ $ python -m stackspin stackspin.example.org create \
+ stackspin.example.org \
+ --ip-address 1.2.3.4
+
+This configures your cluster under the fully qualified domain name (FQDN)
+``stackspin.example.org``, To break down the command:
+
+- the first, positional argument ``stackspin.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/stackspin.example.org`` on
+your provisioning machine.
diff --git a/docs/installation/_use_greenhost_api.rst b/docs/installation/_use_greenhost_api.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2ba2699fbdf86c35ca92ea369cfd0e8dc2dfce02
--- /dev/null
+++ b/docs/installation/_use_greenhost_api.rst
@@ -0,0 +1,86 @@
+**Prerequisites**
+
+Before you can start, you need the following things:
+
+1. An API key with Customer rights.
+
+ .. raw:: html
+
+ <details>
+ <summary><a>Read how to get an API key</a></summary>
+ <p>
+ <ol>
+ <li>In the Cosmos service centre, click your webmaster account name on
+ the top right corner</li>
+ <li>Go to "User settings"</li>
+ <li>Click "API keys"</li>
+ <li>Click "New API key"</li>
+ <li>Click "Generate new key"</li>
+ <li>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.</li>
+ <li>Copy the generated key and run export it to this variable in a
+ terminal:</li>
+ </ol>
+ </p>
+ </details>
+
+ Make sure the Stackspin CLI can use your token by storing it in a
+ ``COSMOS_API_TOKEN`` variable.
+
+ .. code:: bash
+
+ $ export COSMOS_API_TOKEN=<paste your API key here>
+
+ In *the same terminal*, you can now use the ``create`` subcommand
+
+2. An SSH key ID from the Cosmos Service Centre's "VPS Cloud" section. This SSH
+ key will get Root access on the VPS.
+
+ - 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.
+
+ - 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*
+
+3. The ability to create DNS records that point to the VPS that gets created
+
+**Step 1: Create VPS and cluster configuration**
+
+We'll use the ``create`` subcommand of the Stackspin CLI to create a VPS
+and a corresponding configuration file on the provisioning machine.
+
+Here is an example of a complete creation command:
+
+::
+
+ $ python -m stackspin stackspin.example.org create \
+ --create-droplet \
+ --create-hostname stackspin.example.org \
+ --ssh-key-id 112 \
+ --create-domain-records \
+ --subdomain stackspin \
+ example.org
+
+Let's break down the arguments:
+
+- ``--create-droplet``: Use the Greenhost API to create a new VPS
+- ``--create-hostname stackspin.example.org``: Create a VPS with hostname ``stackspin.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 *Step 2: DNS Configuration*. The following records
+ are automatically created:
+
+ - An ``A`` record ``stackspin.example.org`` pointing to the VPSs IP address
+ - A ``CNAME`` record ``*.stackspin.example.org`` pointing to ``stackspin.example.org``.
+
+- ``--subdomain stackspin``: Only needed when you use ``--create-domain-records`` so
+ the Greenhost API can find your domain. Instead of using positional argument
+ ``stackspin.example.org`` you need to provide. If you want to host Stackspin
+ on a root domain, you can omit the ``subdomain`` argument.
diff --git a/docs/installation/create_cluster.rst b/docs/installation/create_cluster.rst
index 58b5195b5d6fd4fb61e2d55e172f0b7d606e7a9f..a62bd9b6e3fbfa48623d555671c465e504c97ce7 100644
--- a/docs/installation/create_cluster.rst
+++ b/docs/installation/create_cluster.rst
@@ -1,238 +1,22 @@
.. _create_kubernetes_cluster:
-===========================
-Create a kubernetes cluster
-===========================
+=========================================
+Create and configure a kubernetes cluster
+=========================================
-This document describes how you can use Stackspin to install
-`k3s`_, a lightweight Kubernetes distribution on a virtual
-private server.
+Below, choose whether you want to install Stackspin on a VPS or an existing
+Kubernetes cluster. We recommend manually installing it on a VPS, this is the
+most tested solution.
-For Stackspin 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.
+.. tab-set::
-Prerequisites
-=============
+ .. tab-item:: A. Install on a VPS
-During these instructions, you are asked to create a VPS, or have a
-bare metal server ready. The server should meet these requirements:
+ .. include:: _install_on_a_vps.rst
-- Debian 11 (bullseye) installed
-- 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
+ .. tab-item:: B. Install on existing cluster
-- ``ssh-agent`` to give you access to your VPS
+ .. include:: _install_on_existing_cluster.rst
-In this guide, we will create a cluster with IP address ``1.2.3.4`` on domain
-``stackspin.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
-Stackspin CLI. First, choose a name (we chose ``stackspin.example.org``) for
-your cluster. Then run the following command to get information about
-the ``create`` subcommand:
-
-::
-
- $ python -m stackspin stackspin.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 Stackspin 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 Stackspin configuration for your VPS by running the
-following command:
-
-::
-
- $ python -m stackspin stackspin.example.org create \
- stackspin.example.org \
- --ip-address 1.2.3.4
-
-This configures your cluster under the fully qualified domain name (FQDN)
-``stackspin.example.org``, To break down the command:
-
-- the first, positional argument ``stackspin.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/stackspin.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 ``stackspin.example.org`` pointing to the VPS's IP address,
-- A ``CNAME`` record ``*.stackspin.example.org`` pointing to ``stackspin.example.org``.
-
-.. Note::
- It is also possible to host Stackspin 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``.
-
-Stackspin 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 Stackspin installation script.
-First, make sure your DNS configuration is propagated. To do so, make
-sure 'ping' shows your VPS's IP address:
-
-::
-
- $ ping stackspin.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
-Stackspin.
-
-::
-
- $ python -m stackspin stackspin.example.org install
-
-
-This will take a few minutes. It installs `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
-.. _k3s: https://k3s.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
+Now that you have a Kuberetes cluster running you can continue to
:ref:`install_stackspin`.
-
-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. ``stackspin.yourdomain.com``), use the
- ``--subdomain`` command as follows:
-
- ::
-
- $ python -m stackspin stackspin.example.org create --subdomain stackspin example.org
-
-- Here is an example of a complete creation command:
-
- ::
-
- $ python -m stackspin stackspin.example.org create \
- --create-droplet \
- --create-hostname stackspin.example.org \
- --ssh-key-id 112 \
- --create-domain-records \
- --subdomain stackspin \
- example.org
-
- Let's break down the arguments:
-
- - ``--create-droplet``: Use the Greenhost API to create a new VPS
- - ``--create-hostname stackspin.example.org``: Create a VPS with hostname ``stackspin.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 ``stackspin.example.org`` pointing to the VPSs IP address
- - A ``CNAME`` record ``*.stackspin.example.org`` pointing to ``stackspin.example.org``.
-
- - ``--subdomain stackspin``: Only needed when you use ``--create-domain-records`` so
- the Greenhost API can find your domain. Instead of using positional argument
- ``stackspin.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/overview.rst b/docs/installation/install_cli.rst
similarity index 82%
rename from docs/installation/overview.rst
rename to docs/installation/install_cli.rst
index 969558b50aeae3104957128551742a8a4d770aef..4cb34dfb609a6152109abb25f54d5a2727af18d2 100644
--- a/docs/installation/overview.rst
+++ b/docs/installation/install_cli.rst
@@ -15,16 +15,13 @@ Installation overview
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
- Stackspin, unless specified otherwise.
-
Setup
=====
+This page will guide you through the installation of the "Stackspin CLI". The
+CLI can be used to set up Stackspin on a different machine that is connected to
+the internet. It also functions as a starting point for running tests.
+
Common prerequisites
--------------------
@@ -37,6 +34,15 @@ Stackspin on an existing cluster, these are the common prerequisites:
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``.
+- You need a recent version of Pip. If you run into problems during ``pip
+ install`` you might need to run ``pip install --upgrade pip``.
+
+.. 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
+ Stackspin, unless specified otherwise.
Clone the Stackspin git repository
-------------------------------------
@@ -49,8 +55,8 @@ and checkout the latest release branch (currently ``v0.7``):
$ git clone -b v0.7 https://open.greenhost.net/stackspin/stackspin.git
$ cd stackspin
-Create a python virtual environment
------------------------------------
+Create a python virtual environment (Optional)
+----------------------------------------------
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
@@ -95,11 +101,8 @@ directory of the git repository. In this tutorial, we're using
$ python -m stackspin stackspin.example.org --help
-Installation options
-====================
+Kubernetes Cluster
+==================
-1. If you want to create a Kubernetes cluster from scratch on a dedicated server
- or virtual machine please start with :ref:`create_kubernetes_cluster` and
- then continue with :ref:`install_stackspin`.
-#. If you want to install Stackspin on an existing Kubernetes cluster you can
- skip the above instructions and start with :ref:`install_stackspin`.
+The next chapter, :ref:`create_kubernetes_cluster`, will explain setting up
+and/or configuring a Kubernetes cluster to install Stackspin on.
diff --git a/docs/installation/install_stackspin.rst b/docs/installation/install_stackspin.rst
index c38b8762317c05bfb5e083545579479f895e34f5..d39c4e34bdc41a91369acaf502e6912223378e0f 100644
--- a/docs/installation/install_stackspin.rst
+++ b/docs/installation/install_stackspin.rst
@@ -1,51 +1,20 @@
.. _install_stackspin:
-====================
+=================
Install Stackspin
-====================
-
-This guide explains how to install Stackspin either on an existing Kubernetes
-cluster that you have setup entirely yourself, or on a cluster you created
-following the Stackspin :ref:`create_kubernetes_cluster` guide.
-Please choose one of the below options:
-
-.. tab-set::
-
- .. tab-item:: A. Install on cluster created with Stackspin cli
-
- If you followed the :ref:`create_kubernetes_cluster` guide to setup a
- Kubernetes cluster using the Stackspin CLI tool you're all set and
- can continue by following the steps below.
-
- .. 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 Stackspin.
-
- **Setup**:
-
- - Create a directory containing your cluster configuration, i.e.
- ``mkdir -p clusters/stackspin.example.org``
- - Copy your ``kube_config.yml`` file inside your cluster config directory
- and rename it to ``kube_config_cluster.yml``:
- ``cp kube_config.yml clusters/stackspin.example.org/kube_config_cluster.yml``
-
- Continue by following the steps below.
+This guide explains how to install Stackspin on the Kubernetes cluster you have
+configured in the previous step.
.. _flux_config:
-Flux configuration
-==================
+Step 1: Flux configuration
+==========================
+
+Flux will run inside your Stackspin cluster to install and upgrade applications.
+It needs to be configured once, using the ``flux`` command line tool and scripts
+provided by us in the Stackspin repository.
.. _flux_prerequisites:
@@ -53,36 +22,40 @@ Prerequisites
-------------
- ``kubectl`` (`installation instructions <https://kubernetes.io/docs/tasks/tools/#kubectl>`__)
-- ``flux version 0.22.0`` `Download flux_0.22.0_linux_amd64.tar.gz <https://github.com/fluxcd/flux2/releases/download/v0.22.0/flux_0.22.0_linux_amd64.tar.gz>`_
+- ``flux version 0.22.0`` (`Download flux_0.22.0_linux_amd64.tar.gz <https://github.com/fluxcd/flux2/releases/download/v0.22.0/flux_0.22.0_linux_amd64.tar.gz>`_)
+
+Configuration
+-------------
Copy the file ``install/.flux.env.example`` to your cluster dir
``clusters/stackspin.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.
+information you need to configure. Make sure not to put any quotes around your
+values, because that can make the resulting yaml files invalid.
+
+Cluster information
+~~~~~~~~~~~~~~~~~~~
-- ``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.
+.. code::
-Make sure not to put any quotes around your values, because that can make the
-resulting yaml files invalid.
+ # The IP address of your cluster
+ ip_address=1.2.3.4
+ # The FQDN of your cluster
+ domain=stackspin.example.org
+ # The system administrator's email address. Alerts are sent to this address
+ admin_email=admin@example.org
Outgoing email
---------------
+~~~~~~~~~~~~~~
-You need to provide email smtp settings so the single sign on system can send
-emails with password recovery links.
-Apps like Nextcloud, Zulip and Alertmanager will also be able to send
-email notifications.
+Stackspin uses SMTP to send emails. This is essential for finishing account
+setups with password recovery links. Additionally, apps like Nextcloud, Zulip
+and Alertmanager will be able to send email notifications from the email address
+configured here.
-.. Note::
- Stackspin does not set up an email server for you. In order to enable
- outgoing emails you need to provide an already existing email account.
+Because Stackspin does not include an email server, you need to search your
+(external) email provider's helpdesk for SMTP configuration details.
-Stackspin uses SMTP to send emails. Search your email provider's helpdesk
-for SMTP configuration details and enter them in the
-``clusters/stackspin.example.org/.flux.env`` file as follows:
+Edit the ``clusters/stackspin.example.org/.flux.env`` file as follows:
.. code::
@@ -106,8 +79,8 @@ for SMTP configuration details and enter them in the
.. _backups-with-velero:
-Backups with Velero
--------------------
+Backups with Velero (Optional)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
@@ -138,7 +111,7 @@ the installation procedure, you have to install the ``velero`` application.
.. _install_core_apps:
-Step 1: Install core applications
+Step 2: Install core applications
=================================
Before you can start, you need to execute a few commands from the installation
@@ -179,7 +152,7 @@ the `git repository <https://open.greenhost.net/stackspin/stackspin>`__.
.. _install_additional_apps:
-Step 2: Install additional applications
+Step 3: Install additional applications
=======================================
After the script completes, you can install applications by running the other
@@ -203,16 +176,19 @@ specific application releases by running ``watch flux get helmreleases
.. _validate_setup:
-Step 3: Validate setup
+Step 4: Validate setup
======================
+Once the installation has been completed, you should be able to log in on
+https://dashboard.stackspin.example.org (as always: replace
+*stackspin.example.org* with your domain). To get the Admin password, run:
+
Because Stackspin is still under development, we would like you to
-follow our `testing instructions <testing.html>`__ to make sure
-that the setup process went well.
+follow our :ref:`testing_guide` to make sure that the setup process went well.
.. _let_us_know:
-Step 4: Let us know!
+Step 5: Let us know!
====================
We would love to hear about your experience installing Stackspin. If you
diff --git a/docs/testing.rst b/docs/testing.rst
index 6d98d81d77fbebf2e4897c0abaf49ee9c20ee1fa..b082635c681a3cba5e6413ca7e6973c3c7f3cfe4 100644
--- a/docs/testing.rst
+++ b/docs/testing.rst
@@ -1,3 +1,5 @@
+.. _testing_guide:
+
Testing guide
=============
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index e699f467a115ea63e30ca5e9dd8fef51a2746e86..e446057722b70c27e4467a9529a9942fa734fff2 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -1,5 +1,7 @@
-Upgrading
-=========
+.. _upgrade_guide:
+
+Upgrade guide
+=============
Upgrading to 0.8.0 (not released yet)
-------------------------------------