diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 4c557f96d79878ae041856806d546ff7701bc5bc..6d6d0776dc8b285e0457e7704b6cddb5b26ff8ca 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -358,6 +358,8 @@ install-stackspin:
- sed -i "s/1.2.3.4/$IP_ADDRESS/" ${CLUSTER_DIR}/.flux.env
- sed -i "s/example.org/$FQDN/" ${CLUSTER_DIR}/.flux.env
- sed -i "/^\s*#.*$/d; /^\s*$/d" ${CLUSTER_DIR}/.flux.env
+ # Disable outgoing mail
+ - sed -i "s/outgoing_mail_enabled=true/outgoing_mail_enabled=false/" ${CLUSTER_DIR}/.flux.env
# Deploy secret/stackspin-cluster-variables
- cp install/kustomization.yaml ${CLUSTER_DIR}
- kubectl create namespace flux-system
diff --git a/docs/comparable_projects.md b/docs/comparable_projects.md
index 81f9cf551e5abc28409c8c83161e074ae8714198..55c8bb13297c70393ffbd23b1a2edfd313568054 100644
--- a/docs/comparable_projects.md
+++ b/docs/comparable_projects.md
@@ -32,7 +32,7 @@ applications or more than five users.
All mentioned platforms require applications running on it to be changed in some
way, for example to make use of the authentication system. Stackspin tries to
steer clear of changing the applications it includes. As long as they support
-OpenID Connect, so you can sign into it, we can usually run the application
+OpenID Connect, so you can sign in to it, we can usually run the application
as-is. In most cases, Stackspin will only need one intervention before an
update can be pushed to users: it needs to be tested. We want to make sure that
an application works together with the platform and other applications before we
diff --git a/docs/index.rst b/docs/index.rst
index 082dbdae91af60c29b0bbc0986ae42bcfd2eab43..a6c9c7c1754feb5ce7a1b0457766b4f97e35c636 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,12 +4,12 @@
contain the root `toctree` directive.
Welcome to Stackspin's documentation!
-========================================
+=====================================
-Stackspin (Stackspin) is a platform that will offer self-managed, click-and-play
-provisioning of online applications for Civil Society Organisations (CSOs).
-Users will be able to easily set up a self-hosted instance of Stackspin, so
-they can keep control over the data that gets entered into these applications.
+Stackspin is a platform that offers self-managed, click-and-play
+provisioning of online applications for Civil Society Organisations (CSOs).
+Users will be able to easily set up a self-hosted instance of Stackspin, so
+they can keep control over the data that gets entered into these applications.
Stackspin is:
@@ -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..0d6b463d48871adaca78e2e5866c1b37125d37f8
--- /dev/null
+++ b/docs/installation/_dns_config.rst
@@ -0,0 +1,19 @@
+Stackspin needs two DNS records that point to your cluster. It is important to
+create these DNS records before you start the installation, so Stackspin can
+secure your connections with https certificates from `Let's Encrypt
+<https://letsencrypt.org>`__.
+
+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 without a dedicated
+ subdomain. That does imply that the included WordPress site will be hosted on
+ your root domain (i.e. ``https://example.org``). In that case, make these DNS
+ records instead:
+
+ - An ``A`` record ``example.org`` pointing to the cluster'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..46a74f6bad9e95c84fcaecfe8c8f4413f46d7b01
--- /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 in to this machine before, you might need to accept the
+SSH hostkey before you can start the installation process. To be sure, log in to
+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..80a91b9f28c804bd1a48edc220334b3fb51d8fbd
--- /dev/null
+++ b/docs/installation/_install_on_existing_cluster.rst
@@ -0,0 +1,28 @@
+Below, we describe how you can install Stackspin on an existing Kubernetes
+cluster. This process can be followed if you have a "managed Kubernetes"
+setup, or if you want to use a Kubernetes version other than K3s.
+
+.. note::
+
+ - Installation on an existing Kubernetes cluster is still experimental and
+ might not work depending on the setup of your cluster/cloud provider.
+ We are happy to receive feedback from your experiences but at the moment we
+ cannot make any guarantees!
+
+**Prerequisites**
+
+- A single-node Kubernetes cluster (multi-node support has not been tested by
+ the Stackspin team)
+- 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..dafce1f53ebb19805f9e30222e766967afaf10c2
--- /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..199dcc1d6203f229d8762b00309ac229b7bb1920
--- /dev/null
+++ b/docs/installation/_use_greenhost_api.rst
@@ -0,0 +1,90 @@
+**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 VPS's 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. If you
+ use the ``--subdomain`` argument, the positional argument **must not** include
+ the subdomain (i.e., in the example command the positional argument is
+ ``example.org`` and not ``subdomain.example.org``).
+
+ 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..0c9dac51686a54180cd6d23f42c57a6c9fc40fea 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 Kubernetes 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 81%
rename from docs/installation/overview.rst
rename to docs/installation/install_cli.rst
index 969558b50aeae3104957128551742a8a4d770aef..6278611d21d50354525dd6915f50fb50bb29f4f4 100644
--- a/docs/installation/overview.rst
+++ b/docs/installation/install_cli.rst
@@ -15,20 +15,14 @@ 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
--------------------
-Wether you want to create a kubernetes cluster first or want to install
+Whether you want to create a Kubernetes cluster first or want to install
Stackspin on an existing cluster, these are the common prerequisites:
- You need Python 3 with its development files, Pip and Git installed
@@ -37,6 +31,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 +52,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 +98,5 @@ directory of the git repository. In this tutorial, we're using
$ python -m stackspin stackspin.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_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..50c86a754da259bbf2b9e23e6740ba60226c5ac2 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.
-- ``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.
+Cluster information
+~~~~~~~~~~~~~~~~~~~
-Make sure not to put any quotes around your values, because that can make the
-resulting yaml files invalid.
+.. code::
+
+ # 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,23 @@ specific application releases by running ``watch flux get helmreleases
.. _validate_setup:
-Step 3: Validate setup
+Step 4: Validate setup
======================
-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.
+Once the installation has been completed, you can log in on
+https://dashboard.stackspin.example.org (as always: replace
+*stackspin.example.org* with your domain). To get your login details, run:
+
+.. code:: bash
+
+ $ python -m stackspin stackspin.example.org admin-credentials
+
+Additionally, because Stackspin is still under development, we would like you to
+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..f2739498a83e06496d6af1b205f65ab3dadaae08 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)
-------------------------------------
@@ -15,7 +17,7 @@ you get started!**
.. code:: bash
- # Log into your Stackspin server
+ # Log in to your Stackspin server
ssh <server>
# Download our upgrade script
wget https://open.greenhost.net/stackspin/stackspin/-/raw/main/upgrade-scripts/to-0.8.0/rename-to-stackspin.sh
@@ -81,7 +83,7 @@ to uniquely identify users.
You can choose from these options:
-1. Manually re-upload and re-share your files after logging into your new user
+1. Manually re-upload and re-share your files after logging in to your new user
for the first time.
2. It is possible to transfer files from your previous user to the new user. To
do so, find your new username. It is visible in Settings -> Sharing behind
diff --git a/docs/usage.rst b/docs/usage.rst
index 2c72761e7651a1e6d9909fda655c464a358bb7ab..3072842db4fcbe96deb82b328a9ce2816ef2eb6c 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -4,10 +4,10 @@ Usage
Stackspin User panel
--------------------
-After all the applications are installed, the first thing to do is log into
+After all the applications are installed, the first thing to do is log in to
`https://admin.stackspin.example.org <https://admin.stackspin.example.org>`__.
This is the "user panel" , a place where you can create, edit and delete users.
-These users can be used to log into the applications listed below.
+These users can be used to log in to the applications listed below.
You can log in with the user "admin". The password can be found by running
.. code:: bash
@@ -150,9 +150,9 @@ Known issues
''''''''''''
If you want admin privileges inside WordPress, you need to set this in the
-Dashboard. Then, you need to log into WordPress again.
+Dashboard. Then, you need to log in to WordPress again.
-If this is your first time logging into WordPress, you have to log out and in
+If this is your first time logging in to WordPress, you have to log out and in
again for your admin privileges to be applied.
For more information and technical details, refer to `the issue in our issue
diff --git a/install/.flux.env.example b/install/.flux.env.example
index c6524c880d1b2111bd833e768727d607d8e5eaf8..68887d58f5e6a9a1ee20e8f0f31f0743b11d28a5 100755
--- a/install/.flux.env.example
+++ b/install/.flux.env.example
@@ -10,8 +10,10 @@ domain=example.org
# Let's Encrypt notifications, etc.
admin_email=admin@example.org
-# Outgoing mail: even if this is disabled, we need values for it.
-outgoing_mail_enabled=false
+# Outgoing mail with SMTP. You can't reset passwords from the web interface if
+# you disable this. Even if you set this to false, Stackspin needs values for
+# the other outgoing_mail_... fields to use in templates.
+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
diff --git a/stackspin/__main__.py b/stackspin/__main__.py
index 14baaec7ca0a922c7e586b63502cd739bbf461a2..ac89e9de03c52fefee0f928cc8c2d6a977321c2a 100755
--- a/stackspin/__main__.py
+++ b/stackspin/__main__.py
@@ -208,6 +208,10 @@ def main(): # pylint: disable=too-many-statements,too-many-branches,too-many-lo
'secrets',
help=("Show Stackspin cluster secrets"))
secrets_parser.set_defaults(func=secrets)
+ admin_credentials_parser = subparsers.add_parser(
+ 'admin-credentials',
+ help=("Show Stackspin admin username and password"))
+ admin_credentials_parser.set_defaults(func=admin_credentials)
args = parser.parse_args()
loglevel = logging.DEBUG if args.verbose else logging.INFO
@@ -254,6 +258,14 @@ def secrets(clus, args):
clus.load_data()
clus.dump_secrets()
+def admin_credentials(clus, args):
+ """
+ Dumps admin username and password and then exits.
+
+ :param cluster.Cluster clus: cluster to show information about
+ """
+ clus.load_data()
+ clus.dump_admin_credentials()
def create(clus, args): # pylint: disable=too-many-branches
"""
diff --git a/stackspin/cluster.py b/stackspin/cluster.py
index fd9f8fdd539a8354c469126569c97906211e038f..482d757fc9a9c4dfc4d77f79154bb9252453cbe1 100644
--- a/stackspin/cluster.py
+++ b/stackspin/cluster.py
@@ -230,7 +230,27 @@ KUBECONFIG={cluster_dir}/kube_config_cluster.yml
app,
app_secret,
namespace)
- print(f'{namespace}/{app}: {app_secret}={secret}')
+ print(f'{namespace}/{app}: {app_secret} = {secret}')
+
+ def dump_admin_credentials(self):
+ """
+ Shows admin credentials
+ """
+ admin_email = self.get_password_from_kubernetes(
+ "stackspin-cluster-variables",
+ "admin_email",
+ "flux-system")
+ admin_password = self.get_password_from_kubernetes(
+ "stackspin-single-sign-on-variables",
+ "userbackend_admin_password",
+ "flux-system")
+ print("You can log into applications with the following credentials:\n")
+ print(f'Admin email address: {admin_email}')
+ print(f'Admin password: {admin_password}')
+ print("\nNote that if you manually changed the admin password, these"
+ " credentials will be outdated. You can always request a"
+ " password reset from the SSO login screen, using this admin"
+ " email address")
def get_password_from_kubernetes(self, secret, key, namespace):
"""