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.
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.
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.
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
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 giton Debian)
ssh-agentto give you access to your VPS
We recommend using a python virtualenv to make sure we do not change any of your other projects. Install virtualenv by running
pip3 install --user venvor
apt install python3-venv
Getting the installation script¶
On your provisioning machine, clone the OpenAppStack git repository
and checkout the latest release branch (currently
$ 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.
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
Setting up OpenAppStack happens in five steps:
Create configuration files.
Configure an A-record for your domain as well as a wild card for the applications hosted on subdomains.
Configure settings for application installations.
Optionally configure outgoing email and/or automated backup settings.
Setup the VPS for OpenAppStack and install k3s, lightweight Kubernetes.
Install the OpenAppStack core applications as well as optional applications.
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
18.104.22.168 on domain
oas.example.org. Substitute these two variables with your IP address and
To set up your cluster, use the
create subcommand of the
OpenAppStack CLI. First, choose a name (we chose
your cluster. Then run the following command to get information about
$ 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 22.214.171.124
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.orgtells the cluster the domain it will be hosted on. This should be a (subdomain of a) domain you own.
--ip-address 126.96.36.199tells 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
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:
oas.example.orgpointing to the VPS’s IP address,
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:
example.orgpointing to the VPS’s IP address,
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.
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 firstname.lastname@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 email@example.com # 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 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
install command will try to log into your machine as the
rootuser using SSH.
install command with the CLI to completely configure your VPS for
$ 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).
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:
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.
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-velero.sh(only if you have configured it in Backups with Velero).
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.