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.
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 [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 it’s 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
pip3 install --user venvor
apt install python3-venv
ssh-agentto give you access to your VPS
- You need Python 3 with it’s development files, Pip and Git installed (
Getting the installation script¶
On your provisioning machine, clone the OpenAppStack git repository and
checkout the latest tagged version (currently
$ git clone -b 0.3.1 https://open.greenhost.net/openappstack/openappstack.git $ cd openappstack
NOTE: Git will display a warning after you use the
gitcommand 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.
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-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 three steps:
Set up cluster
Create configuration files, and optionally create VPS
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
my-cluster) for your cluster. Then run the following command to get
information about the
$ 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
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
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 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
NOTE: 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.
NOTE: You can use the
--acme-stagingargument 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 would be:
Create the OpenAppStack settings for your VPS by running the following command:
$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
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,
NOTE: It is also possible to host openappstack on a domain (with no dedicated subdomain). 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: 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
To start the installation process, run:
$ python -m openappstack my-cluster install
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
openappstack CLI tool.
OpenAppStack uses Flux to install applications. After the installation process has compleded, 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 Usage section.
NOTE: It is possible to re-run the
installcommand. Make sure you re-run it on a machine with the same
secretsas generated the first time. You can achieve this by making sure you have the
clusters/my-clusterdirectory and it contains the same
secretsdirectory before you run the installation command.