OpenAppStack Tutorial

Here’s how you can set up a single-node OpenAppStack cluster. Support for multi-node clusters will come in the future.


  • 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.

DNS entries

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

Clone the OAS bootstrap repo:

git clone

Copy ansible/inventory.yml.example to ansible/inventory.yml and edit it to reflect your cluster.

Also copy ansible/group_vars/all/settings.yml.example to ansible/group_vars/all/settings.yml and edit as you see fit.


  • You need ansible >= 2.7 installed 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 --no-use-wheel to it.


The bootstrap process sets up a single-node kubernetes cluster on the machine and installs the utility tools helmfile, helm, kubectl and rke.

To run the bootstrap process, you need to move into the ansible/ directory, then run

ansible-playbook bootstrap.yml

It will take approximately 5 to 10 minutes to set up your cluster. Please report any installation issues.


Right now, there are two applications installed:

  • Nextcloud, a file sharing and communication platform;
  • ONLYOFFICE, an online document editing suite.

You can access Nextcloud via Use the username admin with the automatically generated Nextcloud password that you can find in the ansible/cluster_data/secrets/ folder on your workstation. ONLYOFFICE is already integrated in your Nextcloud installation which allows you to create and share ONLYOFFICE documents within Nextcloud.

Besides these applications, some other auxiliary components are installed:

  • local-storage provides 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-manager acquires 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 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 workstation.

Managing an existing cluster

Log in to your cluster with:


where USER is the ansible_user you configured in ansible/inventory.yml.

Some programs that are installed on your cluster:

  • kubectl is the Kubernetes control program. For example, run kubectl get pods -n oas to see a list of pods that exist in the oas namespace (system applications like nginx), and kubectl get pods -n oas-apps for all other OpenAppStack applications (like Nextcloud and ONLYOFFICE). Run kubectl --help for help.
  • helm is the “Kubernetes package manager”. Use helm ls to see what apps are installed in your cluster. You can also use it to perform manual upgrades; see helm --help.
  • helmfile is 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.