OpenAppStack Tutorial

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

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

Prerequisites

  • 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 by running pip3 install --user venv or apt install python3-venv

Install OpenAppStack command line tool

On your provisioning machine, clone the OpenAppStack git repository and checkout the latest tagged version (currently 0.2.2):

$ git clone -b 0.2.2 https://open.greenhost.net/openappstack/openappstack.git
$ cd openappstack
NOTE: Git will display a warning after you use the git command saying that you are in a detached HEAD state. This is perfectly normal and you can proceed without any further actions.

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 install command results in a segmentation fault, you can add --no-use-wheel to it.

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

Install OpenAppStack

Setting up OpenAppStack on your VPS happens in three steps:

  1. Set up cluster

    Create configuration files, and optionally create VPS

  2. Install OpenAppStack

    This installs Kubernetes and all the other software that comes with OpenAppStack. See Usage for more information on which applications are installed.

  3. Validate setup

    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 (we chose my-cluster) for your cluster. Then run the following command to get information about the create subcommand:

$ python -m openappstack my-cluster create --help

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.

    1. In the Cosmos service centre, click your name on the top right corner

    2. Go to “User settings”

    3. Click “API keys”

    4. Click “New API key”

    5. Click “Generate new key”

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

    7. Copy the generated key and run export it to this variable in a terminal:

      $ export COSMOS_API_TOKEN=paste your API key here
      
    8. In the same terminal, you can now use the create subcommand

  1. Based on an already existing Greenhost VPS, using the --droplet-id argument.

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

  2. By creating a new VPS through the API, using the --create-droplet argument

    • Make sure to also provide the --hostname and --ssh-key-id arguments.

      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 DOMAIN_NAME positional argument.

    If you use a subdomain (e.g. oas.yourdomain.com), use the --subdomain command 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 --hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org
    

    NOTE: You can use the --acme-staging argument 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.org and on which you can log in with SSH key with ID 112.

    These DNS records will also be created by Greenhost (assuming you own the domain example.org at Greenhost):

    • An A record oas.example.org pointing to the VPSs IP address
    • A CNAME record *.oas.example.org pointing to oas.example.org.

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.

NOTE: You can use the --acme-staging argument 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.

Create the OpenAppStack settings for your VPS by running the following command:

$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --hostname HOSTNAME --subdomain oas example.org
NOTE: If you are automating this, please add the –acme-staging` argument. This ensures you use “staging” certificates from Let’s Encrypt, to reduce the stress on their servers.

DNS entries

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:

  • An A record oas.example.org pointing to the VPSs IP address,
  • A CNAME record *.oas.example.org pointing to oas.example.org.

NOTE: It is also possible to host openappstack on a domain (with no dedicated subdomain). In that case, make these DNS records instead:

  • An A record example.org pointing to the VPSs IP address,
  • A CNAME record *.example.org pointing to example.org.

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.

Installation

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

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

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 the openappstack CLI tool.

You can re-run the install command. Make sure you re-run it on a machine with the same 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.

Usage

When the installation is completed, you will have access to these applications:

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/my-cluster/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 https://office.oas.example.org.

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.

Monitoring

You should be able to access the visual interface to the monitoring system, Prometheus, 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 clusters/my-clusters/secrets/prometheus_grafana_admin_password on your provisioning machine.

Other applications installed into the cluster

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;

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.

SSH access

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.
  • 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. It is recommended you use the openappstack CLI instead of manually running helmfile.