Here’s 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 machine that is not the VPS that will run OpenAppStack. The installation process will generate some secrets that will be saved to this machine.
- 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. Feel free to try OpenAppStack for testing though, and please report any 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;
- 8GB of RAM;
- at least 20GB of disk space for installation, plus more for application data;
- root ssh access.
First, begin with creating DNS records for your cluster. It’s important to start with configuring DNS because depending on your DNS setup/provider, it takes a while to propagate. You need one dedicated subdomain entry and a wildcard entry for everything inside it. For example, create an A record for these domains:
and make them point to your machine’s public IP address.
Configure your cluster¶
On your local machine, clone the OAS bootstrap repo:
$ git clone https://open.greenhost.net/openappstack/openappstack.git
ansible/inventory.yml and edit it to
reflect your cluster.
ansible/group_vars/all/settings.yml and edit as you see fit.
ansible >= 2.7installed on your workstation to run the bootstrap scripts. Please install it using your system package manager.
In the case your system package manager doesn’t provide that particular ansible version, you can install it via the python package manager like this:
pip3 install --user -r ansible/requirements.txt
Hint: if you have several python projects on your computer, consider using virtualenv
Hint: if you get a segmentation fault using above command, you can add
The bootstrap process sets up a single-node kubernetes cluster on the machine
and installs the utility tools
To run the bootstrap process, you need to move into the
$ ansible-playbook bootstrap.yml
It will take approximately 5 to 10 minutes to set up your cluster. Please report any installation issues.
Right now, these end user applications are installed:
You can access Nextcloud via https://files.oas.example.org. Use the username
admin with the automatically generated Nextcloud password that you can find in
ansible/cluster_data/secrets/ folder 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
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;
- Prometheus and Grafana together provide metrics displayed in nice visual dashboards.
You should be able to access the visual interface to the monitoring system at
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
ansible/cluster_data/secrets/prometheus_grafana_admin_password on your
Managing an existing cluster¶
Log in to your cluster with:
$ ssh [email protected]
USER is the
ansible_user you configured in
Some programs that are installed on your cluster:
kubectlis the Kubernetes control program. For example, run
kubectl get pods -n oasto see a list of pods that exist in the
oasnamespace (system applications like nginx), and
kubectl get pods -n oas-appsfor all other OpenAppStack applications (like Nextcloud and ONLYOFFICE). Run
kubectl --helpfor help.
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.