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 Step 3: Create cluster guide. Please choose one of the below options:
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 !
A single-node Kubernetes cluster
kube_config.ymlfile for API access
Configure DNS: Please follow Step 2: Configure DNS how to setup the DNS records for OpenAppStack.
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 (Flux 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.
If you want apps like Nextcloud, RocketChat and Prometheus to be able to send email notifications, you need to provide an email account.
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 email@example.com # 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 firstname.lastname@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
veleroitself; 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
and configure the settings with the
Then continue with the installation procedure as described below. At the end of
the installation procedure, you have to install the
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.
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:
This installs the core of OpenAppStack into your
k3s cluster. To see
what’s included, check the
flux2/infrastructure and the
folders. In addition, it sets up Prometheus and Grafana to monitor your cluster.
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
Nextcloud and Onlyoffice 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
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.