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.

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.

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.

  • 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:

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. Step 1: Set up cluster

    Create configuration files.

  2. Step 2: Configure DNS

    Configure an A-record for your domain as well as a wild card for the applications hosted on subdomains.

  3. Step 3: Additional configuration

    Configure settings for application installations.

    Optionally configure outgoing email and/or automated backup settings.

  4. Step 4: Setup cluster

    Setup the VPS for OpenAppStack and install k3s, lightweight Kubernetes.

  5. Step 5: Install applications

    Install the OpenAppStack core applications as well as optional applications.

  6. Step 6: Validate setup

    This runs a test in the browser to validate that the installation was successful.

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 Advanced cluster creation: Setup with the 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. 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: 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 by default. In order to do this DNS entries need to be created.

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:

# 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

You can enable Velero, 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: 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 rootuser 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.

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: 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.

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:

secret/oas-cluster-variables configured

Next, run:

./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-nextcloud.sh

  • Rocket.Chat with install-rocketchat.sh

  • WordPress with install-wordpress.sh

  • Velero with install-velero.sh (only if you have configured it in 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: Validate setup

Because OpenAppStack is still under development, we would like you to follow our testing instructions 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. If you didn’t please still reach out as described on our contact page 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.