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 Create a kubernetes cluster guide. Please choose one of the below options:

If you followed the Create a kubernetes cluster guide to setup a Kubernetes cluster using the OpenAppStack CLI tool you’re all set and can continue by following the steps below.

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 Step 2: 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 to kube_config_cluster.yml: cp kube_config.yml clusters/oas.example.org/kube_config_cluster.yml

Continue by following the steps below.

Flux configuration

Prerequisites

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

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:

secret/oas-cluster-variables created

Next, run:

./install/install-openappstack.sh

This installs the core of OpenAppStack into your cluster. To see what’s included, check the flux2/infrastructure and the flux2/core folders in the git repository.

Step 2: 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 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 3: 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 4: 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.