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

Warning

  • 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 its 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 release branch (currently v0.5):

$ git clone -b v0.5 https://open.greenhost.net/openappstack/openappstack.git
$ cd openappstack

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 five steps:

  1. Set up cluster

    Create configuration files, and optionally create VPS.

  2. Optional: enable backups using Velero

    Optionally add settings and credentials to enable backups of your cluster to external S3 storage.

  3. Optional: Confifure outgoing email

    Optionally add settings and credentials to enable outgoing emails from applications to your users

  4. Install OpenAppStack

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

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

  • There are two ways to let the installation program know which VPS to use:

    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.

      In that case, 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 <https://service.greenhost.net/cloud/ApiDoc#/default>`__ 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 \
  --create-hostname my-clusters-hostname \
  --subdomain oas \
  example.org
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). That does imply that the included Wordpress site will be hosted on your root domain example.org. 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: Optional: cluster backups using Velero

At this point you can enable Velero, a program that runs on your cluster and uploads backups of your cluster and user data to an S3 storage service of your choice.

If enabled, Velero will create a backup of your cluster once every night and upload it to the S3 storage you configure. This includes:

  • your cluster state. Technically speaking, it will back up all Kubernetes namespaces in your cluster, except velero itself; this includes things like which applications are installed, including their version number and installation-time settings;
  • persistent data of all applications: for example, single sign-on users that you created, Nextcloud files and metadata, Wordpress site data and comments, Rocketchat chat history, etc. A single exception to this is Prometheus data (statistics of system properties), which takes up a lot of space and we consider not valuable enough to back up.

It does not include anything on the VPS that you may have set up but is not part of OpenAppStack, like programs installed via apt, or data added to the VPS disk not through OpenAppStack.

To enable Velero:

  • edit the file clusters/my-cluster/group_vars/all/settings.yml, reviewing all settings under the backup field and entering the data specific to your backup storage location;
  • in that same file clusters/my-cluster/group_vars/all/settings.yml, add 'velero' to the list of enabled_applications;
  • create the directory clusters/my-cluster/secrets;
  • create the file clusters/my-cluster/secrets/s3_access_key, with as only contents your S3 access key;
  • create the file clusters/my-cluster/secrets/s3_secret_key, with as only contents your S3 secret key.

Then continue with the installation procedure as described below.

Step 3. Optional: Configure outgoing email

If you want apps like Nextcloud to be able to send email notifications, you need to provide an email account. If you provide an account, OpenAppStack will configure Nextcloud to send emails from that account.

Note

OpenAppStack does not set up an email server for you. In order to enable outgoing emails you need to provide an already existing email account.

After using the create command, open the file ./clusters/my-cluster/group-vars/all/settings.yml and set the details of your email server. The details that you need to enter here depend on your email provider.

outgoing_mail:
  enabled: true
  fromAddress: "noreply@example.org"
  smtp:
    user: "noreply@example.org"
    password: "**********"
    host: "mail.example.org"
    # Can be one of ["PLAIN", "LOGIN", "NONE"]
    authtype: "PLAIN"
    ssl: true
    port: 465

Right now OpenAppStack only configures Nextcloud to send emails to users.

Step 4: 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 --install-kubernetes

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 completed, 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 next step (validating your setup).

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.

Note

The --install-kubernetes argument installs or updates your VPS’s K3s installation. If you only want to run (or re-run) the part that installs OpenAppStack on your Kubernetes clusters, leave it out.

Step 5: 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.