OpenAppStack Tutorial

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

Warnings

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

Prerequisites

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

  • oas.example.org
  • *.oas.example.org

and make them point to your machine’s public IP address.

Configure your cluster

Clone the OAS bootstrap repo:

git clone https://code.greenhost.net/openappstack/bootstrap.git

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.

Prerequisites

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

Installation

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.

Usage

Right now, there are two applications installed:

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.

Monitoring

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/secrets/prometheus_grafana_admin_password on your workstation.

Managing an existing cluster

Log in to your cluster with:

ssh USER@oas.example.org

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 Collabora). 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.