OpenAppStack installation instructions¶
This document describes how you can install OpenAppStack on a VPS. The installation process wil 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 [open an issue following our contact guide][https://openappstack.net/contact.html).
- 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
8GB of RAM
At least 25GB of disk space for installation, plus more for application data. We recommend starting with 30GB.
Root ssh access
python3installed. On a debian based system:
apt install python3
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)
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
ssh-agentto give you access to your VPS
Getting the installation script¶
On your provisioning machine, clone the OpenAppStack git repository
and checkout the latest tagged version (currently
$ git clone -b 0.4.0 https://open.greenhost.net/openappstack/openappstack.git $ cd openappstack
Git will display a warning after you use the
git command saying that you
are in a detached HEAD state. This is perfectly normal and you can proceed
without any further actions.
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-stable.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
my-cluster as the cluster name. Try it out by running
$ python -m openappstack my-cluster --help
Setting up OpenAppStack happens in five steps:
Set up cluster
Create configuration files, and optionally create VPS.
Optional: enable backups using Velero
Optionally add settings and credentials to enable backups of your cluster to external S3 storage.
Optional: Confifure outgoing email
Optionally add settings and credentials to enable outgoing emails from applications to your users
Install Kubernetes and all the other software that comes with OpenAppStack. See Usage for more information on which applications are installed.
This runs a test in the browser to validate that the installation was successful.
Step 1: Set up cluster¶
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 my-cluster create --help
Option A: Setup with the Greenhost API¶
Before you can start, you need to have an API key with Customer rights.
In the Cosmos service centre, click your webmaster account name on the top right corner
Go to “User settings”
Click “API keys”
Click “New API key”
Click “Generate new key”
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 later.
Copy the generated key and run export it to this variable in a terminal:
$ export COSMOS_API_TOKEN=<paste your API key here>
In the same terminal, you can now use the
There are two ways to let the installation program know which VPS to use:
Based on an already existing Greenhost VPS, using the
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).
By creating a new VPS through the API, using the
In that case, make sure to also provide the
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
If you use a subdomain (e.g.
oas.yourdomain.com), use the
--subdomaincommand as follows:
$ python -m openappstack my-cluster create --subdomain oas example.org
Here is an example of a complete creation command:
$ python -m openappstack my-cluster create \ --create-droplet \ --create-hostname oas.example.org \ --ssh-key-id 112 \ --create-domain-records \ --subdomain oas \ example.org
You can use the
--acme-stagingargument for testing purposes. This ensures you use “staging” certificates from Let’s Encrypt, to reduce the stress on their servers. However, ONLYOFFICE integration requires valid (live) certificates to work.
This will create configuration files for a cluster named
my-cluster. It will also create a Greenhost VPS with the hostname
oas.example.organd on which you can log in with SSH key with ID
These DNS records will also be created by Greenhost (assuming you own the domain
oas.example.orgpointing to the VPSs IP address
Option B: Setup any VPS or bare metal server¶
Skip this step and continue to Installation if you already set up a Greenhost VPS.
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.
You can use the
--acme-staging argument for testing
purposes. If you are automating this, please use this to ensure you
use “staging” certificates from Let’s Encrypt, to reduce the stress
on their servers. However, ONLYOFFICE and single sign-on integration
require valid (live) certificates to work properly so please don’t
use this option by default.
If you want your cluster to be reachable under the fully qualified
domain name (
oas.example.org, the corresponding parameters
Create the OpenAppStack settings for your VPS by running the following command:
$ python -m openappstack my-cluster create \ --ip-address IP_ADDRESS \ --create-hostname my-clusters-hostname \ --subdomain oas \ example.org
Before you continue, if you have not made DNS entries with the CLI tool, you need to make them now. It is important to start with configuring DNS because depending on your DNS setup/provider, it takes a while (sometimes hours) to propagate.
You need one dedicated (sub)domain entry and a wildcard entry for everything inside it. For example, create an A record for these domains:
oas.example.orgpointing to the VPSs 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 VPSs IP address,
OpenAppStack will fetch https certificates with Let’s Encrypt by default. In order to do this DNS entries need to be created. If you don’t need https certificates for your cluster while testing you can skip this step. Please be aware of the limitations of this:
- Onlyoffice won’t work since it requires a valid certificate connecting to Nextcloud.
- You need to be able to resolve the domain names locally.
Step 2: Optional: cluster backups using Velero¶
At this point 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, Rocketchat 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 enable Velero:
- edit the file
clusters/my-cluster/group_vars/all/settings.yml, reviewing all settings under the
backupfield and entering the data specific to your backup storage location;
- in that same file
'velero'to the list of
- create the directory
- create the file
clusters/my-cluster/secrets/s3_access_key, with as only contents your S3 access key;
- create the file
clusters/my-cluster/secrets/s3_secret_key, with as only contents your S3 secret key.
Then continue with the installation procedure as described below.
Step 3. Optional: Configure outgoing email¶
If you want apps like Nextcloud to be able to send email notifications, you need to provide an email account. If you provide an account, OpenAppStack will configure Nextcloud to send emails from that 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.
After using the create command, open the file
and set the details of your email server. The details that you need to enter here
depend on your email provider.
outgoing_mail: enabled: true fromAddress: "firstname.lastname@example.org" smtp: user: "email@example.com" password: "**********" host: "mail.example.org" # Can be one of ["PLAIN", "LOGIN", "NONE"] authtype: "PLAIN" ssl: true port: 465
Right now OpenAppStack only configures Nextcloud to send emails to users.
Step 4: Installation¶
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.
To start the installation process, run:
$ python -m openappstack my-cluster install --install-kubernetes
This will take between 5 and 20 minutes. It generates secrets that will
be added to the
clusters/my-cluster/secrets directory. If you ever
need any credentials after this installation, you can probably find them
there. Make sure this directory stays safe. Feel free to encrypt it
when you are not using the
openappstack CLI tool.
OpenAppStack uses Flux to install applications. After the installation process has completed, Flux has not necessarily finished installing and integrating all the applications. This process usually takes 10-20 minutes to complete, but can also take longer depending on your machine’s compute and/or network resources.
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. Make
sure you re-run it on a machine with the same
generated the first time. You can achieve this by making sure you
clusters/my-cluster directory and it contains the same
secrets directory before you run the installation command.
--install-kubernetes argument installs or updates your VPS’s K3s
installation. If you only want to run (or re-run) the part that installs OpenAppStack
on your Kubernetes clusters, leave it out.