diff --git a/.gitlab/issue_templates/release.md b/.gitlab/issue_templates/release.md
index cc5bc7ee8326d91bef908f5edda3b6ab846fd042..6f96f23ec0084e28d640a60e7a82de8f82bfc860 100644
--- a/.gitlab/issue_templates/release.md
+++ b/.gitlab/issue_templates/release.md
@@ -1,5 +1,11 @@
# Release checklist
+## Before finalizing release
+
+* [ ] Ensure all applications/dependencies/charts are at their latest versions
+ see `.gitlab/issue_templates/update_all_components.md`
+* [ ] Upgrade-test from last release version to `master` succeeds
+
## In the master branch before releasing
* [ ] Create a MR for the master branch for the following changes:
diff --git a/docs/Makefile b/docs/Makefile
index d4bb2cbb9eddb1bb1b4f366623044af8e4830919..2fded69ef22609c81433f29814271a37b46e4f8c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -3,7 +3,7 @@
# You can set these variables from the command line, and also
# from the environment for the first two.
-SPHINXOPTS ?=
+SPHINXOPTS ?= -E
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
diff --git a/docs/README.md b/docs/README.md
index 20e320f26fcbbc6b95b04db6bd3fface9b091c3c..b37ad63e3887cc38190caa6e16f87a1be2b7378d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,9 +4,9 @@ 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:
- firefox _build/html/index.html
+ xdg-open file://$PWD/_build/html/index.html
diff --git a/docs/advanced_installation.rst b/docs/advanced_installation.rst
deleted file mode 100644
index afb92a7ea8da60afeb6eddc8af4480b8065dc563..0000000000000000000000000000000000000000
--- a/docs/advanced_installation.rst
+++ /dev/null
@@ -1,165 +0,0 @@
-=====================
-Advanced installation
-=====================
-
-In this guide we show how to customize your cluster installation, i.e. if you
-want to install additional applications, or change the configuration of extisting
-apps installed by OAS this is the right place. Customizing other parts of your
-cluster is possible but not yet covered by this guide.
-As the name of this guide implies, it is written for users with advanced knowledge
-of the tools behind Openappstack, most importantly: Kubernetes, Helm, Ansible and Flux 2.
-
-
-.. _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.
-
-Customization
--------------
-
-.. warning::
-
- Customizing your OAS cluster could break your cluster in a way that it's not
- easy to recover. Please be aware of the potential risk when proceeding.
-
-Prerequisites
-=============
-
-* A functional OAS cluster installed following the
- `Openappstack installation instructions <installation_instructions.html>`__
-
-Customize OAS applications
-==========================
-
-Apps deployed by OAS are configured using helm values from templates in
-``flux2/apps/<application>/release.yaml``. It is possible to override values
-from the helmrelease by adding a custom ``ConfigMap`` or ``Secret`` to the
-cluster. The secret or configmap name is specified in the ``valuesFrom`` section
-of the ``release.yaml`` file. Read more in the `Flux documentation
-<https://fluxcd.io/docs/migration/helm-operator-migration/#values-from-sources>`__
-
-Example: Customize Nextcloud to work with staging certificates
---------------------------------------------------------------
-
-Our CI pipeline works with staging certificates from Let's Encrypt, for that
-reason we need to allow insecure connections for the integration with
-ONLYOFFICE. You can find the file at ``install/overrides/oas-nextcloud-override.yaml``.
-
-To apply it, run the following commands:
-
-.. code:: bash
-
- # If you want to run this on your provisioning machine, tell kubectl to use
- # your cluster:
- export KUBECONFIG=$PWD/clusters/oas.example.org/kube_config_cluster.yml
- # Check the current state of the helmrelease you want to modify:
- flux get helmrelease -A
- # If all is OK, make sure to apply your override configmap or secret in the
- # same namespace as your helmrelease with the '-n' argument
- kubectl apply \
- -n oas-apps \
- -f ./install/overrides/oas-nextcloud-override.yaml
-
-Adding custom apps to the cluster
-=================================
-
-OpenAppStack uses Flux 2 to install and auto-update applications. If you want to
-install extra applications or other things into the Kubernetes cluster, our
-advice would be to set up your own GitRepository and add it to the Flux system.
-
-When you do this, you are fully responsible for keeping those applications
-secure and updated. If any of those applications is insecure, that can also
-invalidate the security of your OpenAppStack applications, because they are part
-of the same cluster and VPS.
-
-Refer to the `Flux 2 documentation <https://fluxcd.io/docs>`__ for more
-information.
diff --git a/docs/conf.py b/docs/conf.py
index ad6133c985e24133f81574f85c5a35c61764925d..519ad5ae2e60b9adeab3f445b7ae2da4f8de3e8f 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.
@@ -59,3 +60,14 @@ html_static_path = ['_static']
# Readthedocs.io needs us to tell it what the index file is. This defaults to
# 'contents'
master_doc = 'index'
+
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
+#
+# Suppress autosectionlabel extension warnings about duplicate labels, i.e.
+#
+# docs/usage.rst:105: WARNING: duplicate label wordpress, other instance in docs/testing.rst
+#
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-suppress_warnings
+suppress_warnings = ['autosectionlabel.*']
+autosectionlabel_prefix_document = True
diff --git a/docs/customizing.rst b/docs/customizing.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b389c49a728fb4a10ccd0561614668039537b039
--- /dev/null
+++ b/docs/customizing.rst
@@ -0,0 +1,68 @@
+===========
+Customizing
+===========
+
+In this guide we show how to customize your cluster installation, i.e. if you
+want to install additional applications, or change the configuration of extisting
+apps installed by OAS this is the right place. Customizing other parts of your
+cluster is possible but not yet covered by this guide.
+This guide is written for users with advanced knowledge of the tools behind
+Openappstack, most importantly: Kubernetes, Helm, Ansible and Flux 2.
+
+.. warning::
+
+ Customizing your OAS cluster could break your cluster in a way that it's not
+ easy to recover. Please be aware of the potential risk when proceeding.
+
+Prerequisites
+=============
+
+* A functional OAS cluster installed following the
+ `Openappstack installation instructions <installation_instructions.html>`__
+
+Customize OAS applications
+==========================
+
+Apps deployed by OAS are configured using helm values from templates in
+``flux2/apps/<application>/release.yaml``. It is possible to override values
+from the helmrelease by adding a custom ``ConfigMap`` or ``Secret`` to the
+cluster. The secret or configmap name is specified in the ``valuesFrom`` section
+of the ``release.yaml`` file. Read more in the `Flux documentation
+<https://fluxcd.io/docs/migration/helm-operator-migration/#values-from-sources>`__
+
+Example: Customize Nextcloud to work with staging certificates
+--------------------------------------------------------------
+
+Our CI pipeline works with staging certificates from Let's Encrypt, for that
+reason we need to allow insecure connections for the integration with
+ONLYOFFICE. You can find the file at ``install/overrides/oas-nextcloud-override.yaml``.
+
+To apply it, run the following commands:
+
+.. code:: bash
+
+ # If you want to run this on your provisioning machine, tell kubectl to use
+ # your cluster:
+ export KUBECONFIG=$PWD/clusters/oas.example.org/kube_config_cluster.yml
+ # Check the current state of the helmrelease you want to modify:
+ flux get helmrelease -A
+ # If all is OK, make sure to apply your override configmap or secret in the
+ # same namespace as your helmrelease with the '-n' argument
+ kubectl apply \
+ -n oas-apps \
+ -f ./install/overrides/oas-nextcloud-override.yaml
+
+Adding custom apps to the cluster
+=================================
+
+OpenAppStack uses Flux 2 to install and auto-update applications. If you want to
+install extra applications or other things into the Kubernetes cluster, our
+advice would be to set up your own GitRepository and add it to the Flux system.
+
+When you do this, you are fully responsible for keeping those applications
+secure and updated. If any of those applications is insecure, that can also
+invalidate the security of your OpenAppStack applications, because they are part
+of the same cluster and VPS.
+
+Refer to the `Flux 2 documentation <https://fluxcd.io/docs>`__ for more
+information.
diff --git a/docs/index.rst b/docs/index.rst
index 3176794a39d07197351fa174e8b46527f8d1853e..309c7d1d109357fb14368826ffb893da6dbdd4c2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,16 +24,33 @@ For more information, go to `the OpenAppStack website`_.
.. toctree::
:maxdepth: 2
- :caption: Contents:
+ :caption: Installation
+
+ installation/overview
+ installation/create_cluster
+ installation/install_oas
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Usage
- installation_instructions
- advanced_installation
- testing_instructions
usage
+ testing
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Administration
+
maintenance
+ upgrading
+ customizing
troubleshooting
security
- upgrading
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Reference
+
+ reference
comparable_projects
design
- reference
diff --git a/docs/installation/create_cluster.rst b/docs/installation/create_cluster.rst
new file mode 100644
index 0000000000000000000000000000000000000000..1e1ca1ef037ee66c00cd147a30a86b2aa133e333
--- /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:
+
+- Debian "buster" 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
+
+- ``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 0000000000000000000000000000000000000000..f0ad750d09d1fcf6bebf10297aab21e31a7a4e92
--- /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 2>/dev/null || 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 0000000000000000000000000000000000000000..883228ea00b0ad4c79bed2ef2bd8469ca098e88f
--- /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/installation_instructions.rst b/docs/installation_instructions.rst
deleted file mode 100644
index e7ee49b260ef406bbff5331902051391ed6bf777..0000000000000000000000000000000000000000
--- a/docs/installation_instructions.rst
+++ /dev/null
@@ -1,407 +0,0 @@
-OpenAppStack installation instructions
-======================================
-
-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_instructions.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/maintenance.rst b/docs/maintenance.rst
index 61a7a5233a2c49e32684200de080d23a1fcdfb2f..ac8b107d7f2b8356607fcc05e6116b5a1cd60b31 100644
--- a/docs/maintenance.rst
+++ b/docs/maintenance.rst
@@ -1,5 +1,5 @@
-Maintaining an Openappstack cluster
-===================================
+Maintenance
+===========
Logging
-------
diff --git a/docs/security.rst b/docs/security.rst
index 3dbb4ebf6d282248b54d81a5f5192ededf70d5a8..099bfa76ad0e4009aa24648f188c285eb7f32ba0 100644
--- a/docs/security.rst
+++ b/docs/security.rst
@@ -12,7 +12,7 @@ If you like to limit who can access your cluster resources you can configure
the OAS ingress (`ingress-nginx <https://kubernetes.github.io/ingress-nginx>`__)
to only accept connections from a certain IP address or range.
-Follow the :ref:`Customize OAS applications` instructions, but use the following
+Follow the :ref:`customizing:Customize OAS applications` instructions, but use the following
secret as ``install/overrides/oas-nginx-override.yml`` and apply the secret in
the ``oas`` namespace instead of ``oas-apps``. Replace the source range with the
IP address ranges you want to allow.
diff --git a/docs/testing.rst b/docs/testing.rst
new file mode 100644
index 0000000000000000000000000000000000000000..45d2f150ac5fd19ef3e6d0645f7ea20d7e8b82b3
--- /dev/null
+++ b/docs/testing.rst
@@ -0,0 +1,124 @@
+Testing guide
+=============
+
+Great that you want to take OpenAppStack for a test drive !
+This guide contains instructions to get you going, some pointers on what we think
+would be useful to test, and guesses at what results of those tests
+would be useful to write down. At any point please feel invited to test
+whatever functionality you come across, and reporting whatever you think
+is interesting. Our contact details are listed
+`here <https://openappstack.net/contact.html>`__, and we’ll descibe how
+to give feedback via our issue tracker at the `end of these
+instructions <#providing-feedback>`__.
+
+During these instructions, please replace *example.org* with your own
+domain name.
+
+OAS installation
+----------------
+
+First we’d like you to setup an OpenAppStack cluster by yourself,
+following the :ref:`installation_overview` and :ref:`usage:Usage` documentation and make sure
+you complete all steps.
+
+Command line tests
+------------------
+
+Please :ref:`troubleshooting:Run the CLI tests` which checks
+the overall functionality of your cluster and include the output in your
+feedback.
+
+
+Testing Instructions for all apps
+---------------------------------
+
+Please login using single sign-on as ``admin`` and see if you have admin
+rights granted (usually there’s an app specific admin panel available or
+admin functionality like configuring users). Afterwards logout and login
+again as the non-admin single-sign-on user you created earlier in the
+OAS admin panel. You should *not* have any admin privileges now.
+
+Testing Instructions for specific apps
+--------------------------------------
+
+Nextcloud
+~~~~~~~~~
+
+Please browse to Nextcloud using the link from your user dashboard app
+list and try to log in using single sign-on. Use the button labeled
+``Login with OpenAppStack``. Please try logging in with your admin
+account and configure the email settings as shown in the Usage doc.
+After that please login with the user you created in the user panel.
+
+Files & synchronization
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Please try uploading, downloading, moving or copying files.
+
+Calendar
+^^^^^^^^
+
+Please test the basic functionality of the calendar, including advanced features
+like recurrence, custom notifications or inviting attendees.
+
+Passwords
+^^^^^^^^^
+
+Please create and manage different passwords. In addition to that please try
+
+Nextcloud sync applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Please try syncing with your smartphone or desktop using one of the apps
+ mentioned in :ref:`Usage:Nextcloud`.
+
+Onlyoffice
+~~~~~~~~~~
+
+Creating a new office document
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+From the main Nextcloud webpage, please try to create a new office
+document, by clicking the round ``plus`` button near the top of the
+screen, then picking the ``Document`` type with the blue icon (third one
+from below on my screen), and enter a name for it. After that, please
+try some basic editing of the document, and save it. Maybe check you can
+open it again afterwards, and that it has the contents that you saved
+earlier.
+
+Collaborating on an office document
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This part of the test requires the cooperation of another person; feel
+free to skip it now if that’s not convenient at this point.
+
+- First, try to share your document with a different user.
+- Then, try to open the shared document from a few different user
+ accounts simultaneously, and let all participants edit the document
+ mercilessly. There are also some collaboration features that you may
+ want to try: on the left of the Onlyoffice screen there are buttons
+ for chat and for text comments.
+
+Wordpress
+~~~~~~~~~
+
+Please try to login as the new user you created earlier by pressing “Log
+in†and using the ``Login with OpenID Connect`` button.
+
+At the moment Administrator privileges will not be available for single
+sign-on users of WordPress. You can sign in with the automatically
+created administrator account. The username is ``admin`` and the
+password can be found in the ``wordpress_admin_password`` file in the
+``secrets`` folder of your provisioning machine’s config directory.
+
+Providing feedback
+------------------
+
+If you have not done so already, please create an account on
+https://open.greenhost.net (or login with your existing github account)
+and `create a new
+issue <https://open.greenhost.net/openappstack/openappstack/issues/new>`__
+using the ``Feedback`` template.
+
+Thanks a lot for your testing work! We’ll use your input to try to
+improve OpenAppStack.
diff --git a/docs/testing_instructions.md b/docs/testing_instructions.md
deleted file mode 100644
index 698ad6de7e38b617933aad242b0246a22bc96cff..0000000000000000000000000000000000000000
--- a/docs/testing_instructions.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# A testing guide and test reporting form for testers of the OpenAppStack project
-
-Great that you want to take OpenAppStack for a test drive.
-This tutorial contains instructions to get you going,
-some pointers on what we think would be useful to test, and guesses at what results of those tests would be
-useful to write down.
-At any point please feel invited to test whatever functionality you come across, and reporting whatever you
-think is interesting. Our contact details are listed [here](https://openappstack.net/contact.html), and we'll
-descibe how to give feedback via our issue tracker at the [end of these instructions](#providing-feedback).
-
-During these instructions, please replace *example.org* with your own domain
-name.
-
-## Installation
-
-First we'd like you to setup an OpenAppStack cluster by yourself, following the
-[installation tutorial](https://docs.openappstack.net/en/latest/installation_instructions.html).
-
-## Command line tests
-
-Please run the [command line tests](troubleshooting.md) which checks the overall
-functionality of your cluster and include the output in your feedback.
-
-## Usage
-
-Please go through the [Usage documentation](./usage.md) and make sure you
-complete all steps.
-
-## Testing Instructions for all apps
-
-Please login using single sign-on as `admin` and see if you have admin rights
-granted (usually there's an app specific admin panel available or admin
-functionality like configuring users).
-Afterwards logout and login again as the non-admin single-sign-on user
-you created earlier in the OAS admin panel. You should *not* have any admin
-privileges now.
-
-## Testing Instructions for specific apps
-
-### Nextcloud
-
-#### Logging into Nextcloud
-
-Please browse to Nextcloud using the link from your user dashboard app list and
-try to log in using single sign-on. Use the button labeled `Login with OpenAppStack`.
-Please try logging in with your admin account and configure the email settings
-as shown in the Usage doc.
-After that please login with the user you created in the user panel.
-
-#### Nextcloud client application
-
-* If you like, please try the [Nextcloud desktop client](https://nextcloud.com/clients/), connect it to your OpenAppStack instance, and use it to manage some files.
-* If you like, please try the [Nextcloud mobile client](https://nextcloud.com/clients/) for your smartphone, connect it to your OpenAppStack instance, and use it to download and/or open some files, upload a new file, etc.
-
-
-### Onlyoffice
-
-#### Creating a new office document
-
-From the main Nextcloud webpage, please try to create a new office document, by clicking the round `plus` button near the top of the screen, then picking the `Document` type with the blue icon (third one from below on my screen), and enter a name for it. After that, please try some basic editing of the document, and save it. Maybe check you can open it again afterwards, and that it has the contents that you saved earlier.
-
-#### Collaborating on an office document
-
-This part of the test requires the cooperation of another person; feel free to skip it now if that's not convenient at this point.
-
-* First, try to share your document with a different user.
-* Then, try to open the shared document from a few different user accounts simultaneously, and let all participants edit the document mercilessly.
- There are also some collaboration features that you may want to try: on the left of the Onlyoffice screen there are buttons for chat and for text comments.
-
-
-### Wordpress
-
-Please try to login as the new user you created earlier by pressing "Log in" and
-using the `Login with OpenID Connect` button.
-
-At the moment Administrator privileges will not be available for single sign-on
-users of WordPress. You can sign in with the automatically created administrator
-account. The username is `admin` and the password can be found in the
-`wordpress_admin_password` file in the `secrets` folder of your provisioning
-machine's config directory.
-
-
-## Providing feedback
-
-If you have not done so already, please create an account on [https://open.greenhost.net](https://open.greenhost.net)
-(or login with your existing github account) and [create a new issue](https://open.greenhost.net/openappstack/openappstack/issues/new) using the `Feedback` template.
-
-Thanks a lot for your testing work! We'll use your input to try to improve OpenAppStack.
diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index c9ded3b0f99a60d07f87ccd16bcc6051eed89680..94b3f47b2a156b4ce36cff650d34a0e03c7d848b 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -66,13 +66,13 @@ Run all tests
py.test -s --ansible-inventory=${CLUSTER_DIR}/inventory.yml --hosts='ansible://*'
-Test all applications
+Test all applications
'''''''''''''''''''''
This will check for:
* The applications return proper certificates
-* All helm releases are successfully installed
+* All helm releases are successfully installed
* All app pods are running and healthy (this test includes all optional
applications)
@@ -262,7 +262,7 @@ In this example we fix a failed certificate request for
*https://chat.oas.example.org*. We will start by checking if ``cert-manager``
is set up correctly.
-Is your cluster using the live ACME server?
+Is your cluster using the live ACME server?
.. code:: bash
@@ -278,7 +278,7 @@ Are all cert-manager pods in the `oas` namespace in the `READY` state ?
$ kubectl -n cert-manager get pods
Cert-manager uses a "custom resource" to keep track of your certificates, so you
-can also check the status of your certificates by running:
+can also check the status of your certificates by running:
This returns all the certificates for all applications on your system. The
command includes example output of healthy certificates.
@@ -387,7 +387,7 @@ If all your ``kustomizations`` are in a ``Ready`` state, take a look at your
cluster$ flux get helmreleases -A
Often, you can resolve complications with ``kustomizations`` or ``helmreleases``
-by telling Flux to *reconcile* them:
+by telling Flux to *reconcile* them:
.. code:: bash
@@ -413,6 +413,5 @@ OAS installation in order to start from scratch:
cluster$ /usr/local/bin/k3s-killall.sh
cluster$ systemctl disable k3s
- cluster$ mount | egrep '(kubelet|nsfs|k3s)' | cut -d' ' -f 3 | xargs --no-run-if-empty -n 1 umount
cluster$ rm -rf /var/lib/{rancher,OpenAppStack,kubelet,cni,docker,etcd} /etc/{kubernetes,rancher} /var/log/{OpenAppStack,containers,pods} /tmp/k3s /etc/systemd/system/k3s.service
cluster$ systemctl reboot
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
index 26d2da8c0283d68bc10997286d1540d7fcf6f61b..efe906978a9a8deb5045f675d9b9de4de02f6d8f 100644
--- a/docs/upgrading.rst
+++ b/docs/upgrading.rst
@@ -1,5 +1,5 @@
-Upgrading OpenAppStack
-======================
+Upgrading
+=========
Upgrading to 0.7.0
------------------
@@ -24,7 +24,7 @@ The yq needed here can be installed by running ``sudo snap install yq``,
instructions](http://mikefarah.github.io/yq/#install).
-To back-up your secrets, run the following script:
+To back-up your secrets, run the following script:
.. code:: bash
@@ -45,7 +45,7 @@ To back-up your secrets, run the following script:
kubectl get secret -o yaml -n flux-system oas-nextcloud-variables > secrets-backup/oas-nextcloud-variables.yaml
This script assumes you have all applications enabled. You might get an error
-like:
+like:
.. code:: bash
@@ -57,7 +57,7 @@ lines under "data:", rename the field to ``wekan_oauth_client_secret`` and enter
a different random password. Make sure to base64 encode it (``echo "<your random
password>" | base64``).
-If you get the error several times, that means ther
+If you get the error several times, that means ther
This script creates a directory called ``secrets-backup`` and places the secrets
that have been generated by Helm in it as ``yaml`` files.
@@ -69,7 +69,7 @@ Flux will now start updating your cluster to version 0.7. This process will fail
because it will remove the secrets that you just backed up. Make
sure that the ``oas-secrets`` helmrelease has been removed by running ``flux get
hr -A``. You might also see that some helmreleases start failing to be installed
-because important secrets do not exist anymore.
+because important secrets do not exist anymore.
As soon as the ``oas-secrets`` helmrelease does not exist anymore, you can run
the following code:
@@ -112,14 +112,14 @@ SSO helm upgrade failed
.. code::
- oas single-sign-on False Helm upgrade failed: template: single-sign-on/templates/secret-oauth2-clients.yaml:9:55: executing "single-sign-on/templates/secret-oauth2-clients.yaml" at <b64enc>: invalid value; expected string 0.2.2 False
+ oas single-sign-on False Helm upgrade failed: template: single-sign-on/templates/secret-oauth2-clients.yaml:9:55: executing "single-sign-on/templates/secret-oauth2-clients.yaml" at <b64enc>: invalid value; expected string 0.2.2 False
This means that the ``single-sign-on`` helmrelease was created with empty oauth
secrets. The secrets will get a value once the ``core`` *kustomization* is
reconciled: ``flux reconcile ks core`` should solve the problem.
If that does not solve the problem, you should check if the secret contains a
-value for all the apps:
+value for all the apps:
.. code::
@@ -144,7 +144,8 @@ Loki upgrade retries exhausted
While running ``flux get helmrelease -A``, you'll see:
.. code::
- oas loki False upgrade retries exhausted 2.5.2 False
+
+ oas loki False upgrade retries exhausted 2.5.2 False
This happens sometimes because Loki takes a long time to upgrade. Usually it is
solved by running ``flux reconcile hr loki -n oas`` again.
@@ -158,8 +159,8 @@ 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:`OpenAppStack installation
- instructions` for more information.
+ 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
production.
@@ -271,4 +272,3 @@ intervention.
.. _reach out to us: https://openappstack.net/contact.html
.. _Flux: https://fluxcd.io
-
diff --git a/docs/usage.rst b/docs/usage.rst
index 4b010619ec287d099ea15788191d9267e7458702..a32cc6bb4922734b3c8a19e1f8e110fa010c115c 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -1,10 +1,14 @@
Usage
=====
+OAS User panel
+--------------
+
After all the applications are installed, the first thing to do is log into
-https://admin.oas.example.org. This is the "user panel", a place where
-you can create, edit and delete users. You can log in with the user "admin". The
-password can be found by running
+`https://admin.oas.example.org <https://admin.oas.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.
+You can log in with the user "admin". The password can be found by running
.. code:: bash
@@ -14,32 +18,16 @@ Search for ``userbackend_admin_password``.
After logging in, you will see an overview of all the installed applications
your user has access to. For more information on how to create users and give
-them access to applications, take a look at the [user panel
-documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).
+them access to applications, take a look at the `user panel documentation
+<https://docs.openappstack.net/projects/user-panel/en/latest>`_.
.. 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.
-
-Core applications
------------------
-
-These applications are available after the installation is completed
-successfully:
-
-OAS User panel
-~~~~~~~~~~~~~~
-
-The `OAS user panel <https://open.greenhost.net/openappstack/user-panel/>`__
-can be used to create and edit users. These users can be used to log into the
-applications listed below.
-The user panel is available at https://admin.oas.example.org. You can login
-as `admin` using the `userbackend_admin_password` password from your secrets
-folder.
+ optional application in :ref:`additional_apps` of the installation procedure.
-After logging in to the user panel follow the [user panel documentation](https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user)
-to create a new user.
+For creating users follow the `user creation documentation
+<https://docs.openappstack.net/projects/user-panel/en/latest/#creating-a-new-user>`_.
*Note*: The email address is important because some applications need a valid
email address for notification mails.
@@ -51,6 +39,12 @@ in the last step using single sign-on.
Links to all available apps are shown in the userpanel dashboard, which can
be used to access these apps without a need to bookmark all URLs.
+Core applications
+-----------------
+
+These applications are available after the installation is completed
+successfully:
+
Grafana
~~~~~~~
@@ -72,7 +66,49 @@ Nextcloud
~~~~~~~~~
`Nextcloud <https://nextcloud.com/>`__ is a file sharing and communication
-platform.
+platform. These Nectcloud apps can be accessed from the top navigation bar:
+
+Files & synchronization
+'''''''''''''''''''''''
+
+You can access your files with the Nextcloud Web interface and create,
+preview, edit, delete, share, and re-share files.
+See the `Files & synchronization user manual
+<https://docs.nextcloud.com/server/latest/user_manual/en/files/index.html>`_ for
+general usage and `Desktop and mobile synchronization
+<https://docs.nextcloud.com/server/latest/user_manual/th/files/desktop_mobile_sync.html>`_
+for setting up file sync on your mobile or dektop device.
+
+Calendar
+''''''''
+
+The Nextcloud Calendar app works similar to other calendar applications you
+can sync your Nextcloud calendars and events with.
+Follow the `Calendar user manual
+<https://docs.nextcloud.com/server/latest/user_manual/en/pim/calendar.html>`_
+for general usage and the
+`Nextcloud groupware docs <https://docs.nextcloud.com/server/latest/user_manual/th/pim/index.html>`
+for syncing your calendars with your mobile or desktop devices.
+
+Passwords
+'''''''''
+
+A simple, yet feature rich password manager for Nextcloud.
+See `Passwors user handbook
+<https://git.mdns.eu/nextcloud/passwords/wikis/users/index>`_
+for more details, including using the `Browser extenstions
+<https://git.mdns.eu/nextcloud/passwords/wikis/Users/Index#browser-extension>`_.
+
+These are the mobile apps that you can use to access your passwords from your
+smartphone:
+
+* [NC passwords app for Android (by joleaf)](https://gitlab.com/joleaf/nc-passwords-app)
+* [Nexcloud password app for Android (by daper)](https://github.com/daper/nextcloud-passwords-app)
+* [Nextcloud passwords for iOS](https://github.com/johannes-schliephake/nextcloud-passwords-ios)
+
+You'll find how to configure file or calendar sync with your smartphone or
+desktop in the `Nextcloud Groupware documentation
+<https://docs.nextcloud.com/server/latest/user_manual/th/pim/index.html>`_.
Onlyoffice
~~~~~~~~~~
@@ -82,15 +118,6 @@ online document editing suite. Your can open documents in Onlyoffice by clicking
them in Nextcloud. You can open new documents by clicking the "Plus" button in
Nextcloud and selecting Document, Spreadsheet or Presentation.
-.. warning::
-
- OpenAppStack has a known issue that can cause loss of ONLYOFFICE
- documents when the machine gets restarted or loses access to its disk.
-
- Track the following issue to see if it is solved: https://open.greenhost.net/openappstack/nextcloud/-/issues/967
-
- We are working hard to resolve the issue.
-
RocketChat
~~~~~~~~~~
@@ -99,11 +126,9 @@ RocketChat
Wekan
~~~~~
-`Wekan https://wekan.github.io/`__ is a Kanban board application.
+`Wekan <https://wekan.github.io>`__ is a Kanban board application.
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.