This document describes how you can set up a single-node OpenAppStack cluster. Support for multi-node clusters 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.
- A virtual machine or bare metal server with:
- Current Debian stable “buster”;
- A public IP address;
- 6GB of RAM;
- At least 20GB of disk space for installation, plus more for application data;
- root ssh access.
- Python installed
- A trusted local machine to run the installer on:
- You need Python 3 and Git installed (
apt install python3 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
- You need Python 3 and Git installed (
Install OpenAppStack command line tool¶
On your provisioning machine, clone the OpenAppStack git repository:
$ git clone https://open.greenhost.net/openappstack/openappstack.git $ cd openappstack
If you installed
virtualenv, 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.txt
Hint: if the
pip3 installcommand results in a segmentation fault, you can add
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. Try it out by running
$ python -m openappstack my-cluster --help
Setting up OpenAppStack on your VPS happens in three steps:
Set up cluster
Create configuration files, and optionally create VPS
This installs 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.
Set up cluster¶
To set up your cluster, use the
create subcommand of the OpenAppStack CLI.
First, choose a name for your cluster. Then run the following command to get
information about the
$ python -m openappstack CLUSTER_NAME create --help
CLUSTER_NAME with your chosen name.
There are two options to create a cluster:
Use a Greenhost VPS¶
For this to work, you need to have an API key with Customer rights.
In the Cosmos service centre, click your 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.
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
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.
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 create --subdomain oas example.org`.
Here is an example of the complete creation command:
python -m openappstack my-cluster create --create-droplet --hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org
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
Any other VPS or bare metal server¶
If you want to follow this step, we assume you already have a VPS. You’ll need its hostname and its IP address. Also check that your VPS meets our prerequisites.
WARNING: the OpenAppStack installation makes substantial changes to your whole VPS and needs root access. It is not advised to follow these instructions on a VPS that you are using for something else too.
Create the OpenAppStack settings for your VPS by running the following command:
$ python -m openappstack create --ip-address IP_ADDRESS --hostname 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,
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.
Before you start the installation, make sure your DNS is propagated. To do so, make sure ‘ping’ shows your VPS’s IP address:
$ ping oas.example.org
To start the installation process, run:
$ python -m openappstack my-cluster install
This will take approximately 5-10 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.
You can re-run the
install command. Make sure you re-run it on a machine with
secrets as generated the first time. You can achieve this by making
sure you have the
clusters/my-cluster directory and it contains the same
secrets directory before you run the installation command.
When the installation is completed, you will have access to these applications:
- Nextcloud, a file sharing and communication platform;
- ONLYOFFICE, an online document editing suite.
- Grafana that shows you information about the status of your cluster. Read more about Grafana in the monitoring chapter below
You can access Nextcloud via https://files.example.org. Use the username
admin with the automatically generated Nextcloud password that you can find in
clusters/maarten/secrets/nextcloud_admin_password on your local machine.
ONLYOFFICE is already integrated in your Nextcloud installation which allows you
to create and share ONLYOFFICE documents within Nextcloud. ONLYOFFICE runs on
Known limitations of Nextcloud & ONLYOFFICE¶
- Nextcloud does not send emails yet. You can configure sending emails by going to Settings -> Basic settings -> Email server and entering SMTP email credentials.
You should be able to access the visual interface to the monitoring system,
https://grafana.oas.example.org/. A user
admin is created at
installation time; the password that was generated during installation is stored
in the file
your provisioning machine.
Other applications installed into the cluster¶
Besides these applications, some other auxiliary components are installed:
local-storageprovides an easy way for the cluster to use a directory on the node (by default
/var/lib/OpenAppStack/local-storage) for storage;
- nginx is a webserver that functions as a so-called ingress controller, routing web traffic that enters the cluster to the various applications;
cert-manageracquires and stores Let’s Encrypt certificates, enabling encrypted web traffic to all applications running in the cluster;
Managing an existing cluster¶
You can use
kubectl, the Kubernetes control program, to find and manipulate
your Kubernetes cluster. Once you have installed
kubectl, to get access to your
cluster with the OAS CLI:
$ python -m openappstack my-cluster info
Look for these lines:
To use kubectl with this cluster, copy-paste this in your terminal: export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
Copy the whole
export line into your terminal. In that terminal, kubectl
will connect to your cluster.
NOTE: you have to repeat this step in new terminals and terminal tabs.
Alternatively, you can SSH login to your VPS. Some programs that are available to the root user on the VPS:
kubectl, the Kubernetes control program. The root user is connected to the cluster automatically.
helmis the “Kubernetes package manager”. Use
helm lsto see what apps are installed in your cluster. You can also use it to perform manual upgrades; see
helmfileis a high-level tool to manage your app installations. Its manual usage is a bit tricky since current helmfile config depends on environmental variables to be present. It is recommended you use the
openappstackCLI instead of manually running