OpenAppStack installation instructions

This document describes how you can install OpenAppStack on a VPS. The installation process wil set up a “Kubernetes cluster” which runs several open source applications. More information about the applications can be found on the OpenAppStack website.

We will set up a “single-node” OpenAppStack cluster. This means everything runs on the same VPS. Support for “multi-node” clusters (a Kubernetes cluster on more than one VPS) 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

  • During these instructions, you are asked to create a VPS, or have a bare metal server ready. The server should meet these requirements:

    • Current Debian stable “buster”

    • A public IP address

    • The ability to create DNS records for this IP

    • 8GB of RAM

    • At least 25GB of disk space for installation, plus more for application data. We recommend starting with 30GB.

    • Root ssh access

    • python3 installed. On a debian based system:

      apt install python3

  • A trusted machine to run the installer on (we call this the provisioning machine). All the commands listed in these instructions should be run on the provisioning machine, unless specified otherwise.

    • You need Python 3 with it’s development files, Pip and Git installed (apt install python3-pip python3-dev 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
    • ssh-agent to give you access to your VPS

Getting the installation script

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

$ git clone -b 0.3.1 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.

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

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 happens in three steps:

  1. Set up cluster

    Create configuration files, and optionally create VPS

  2. Install OpenAppStack

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

Step 1: 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, using the Greenhost API or using any other machine. Choose one of these options, and skip to the “Installation” subchapter afterwards.

Option A: Setup with the Greenhost API

  • Before you can start, you need to have an API key with Customer rights.

    1. In the Cosmos service centre, click your webmaster account 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 --create-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 --create-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.

Option B: Setup any VPS or bare metal server

Skip this step and continue to Installation if you already set up a Greenhost VPS.

If you want to install OpenAppStack on a non-Greenhost VPS, we assume you already have a machine with a world-facing IP address. Make sure that your VPS meets our prerequisites. You’ll need its hostname and its IP address.

NOTE: You can use the --acme-staging argument for testing purposes. If you are automating this, please use this to ensure you use “staging” certificates from Let’s Encrypt, to reduce the stress on their servers. However, ONLYOFFICE and single sign-on integration require valid (live) certificates to work properly so please don’t use this option by default.

If you want your cluster to be reachable under the fully qualified domain name (FQDN) oas.example.org, the corresponding parameters would be:

  • --subdomain: oas
  • the DOMAIN positional argument: example.org

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

$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
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.

Step 2: Installation

You’re almost ready to start the OpenAppStack installation script. First, make sure your DNS configuration is propagated. To do so, make sure ‘ping’ shows your VPS’s IP address:

$ ping oas.example.org

The install command will try to log into your machine as the rootuser using SSH.

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.

OpenAppStack uses Flux to install applications. After the installation process has compleded, Flux has not necessarily finished installing and integrating all the applications. This process usually takes 10-20 minutes to complete, but can also take longer depending on your machine’s compute and/or network resources.

In the future, we will add commands that show you the status of the application installation. For now, just wait half an hour for everything to settle, and then continue to the Usage section.

NOTE: It is possible to 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.

Step 3: Validate setup

Because OpenAppStack is still under development, we would like you to follow our testing instructions to make sure that the setup process went well.