Create and configure a kubernetes cluster

Below, choose whether you want to install Stackspin on a VPS or an existing Kubernetes cluster. We recommend manually installing it on a VPS, this is the most tested solution.

We recommend manually installing Stackspin on a Greenhost VPS as explained below. However, if you plan on installing many Stackspin instances, click the tab “ADVANCED: Use the Greenhost API” to learn how to automatically create VPSs and DNS records and install Stackspin on them.

This document describes how you can use Stackspin’s CLI to install k3s, a lightweight Kubernetes distribution, on a virtual private server.

For Stackspin we will set up a “single-node” kubernetes 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.

Prerequisites

These instructions assume you have a VPS or other kind of server ready that meets the following requirements:

  • Debian 12 (bookworm) installed

  • A public IPv4 address (Dual-Stack/IPv6 only is not yet supported)

  • The ability to create DNS records for this IP

  • The VPS meets the system requirements below

  • At least 40GB of disk space for installation and monitoring data, plus more for application data. We generally recommend to keep disk usage under 80%.

  • Root ssh access

System requirements

The system requirements depend on which applications you want to install into Stackspin. The following table shows the minimum requirements for each application (1000m CPU means 1 core). Sum up the requirements of all the applications you wish to install, together with the “Core components”. That is the amount of memory and CPU you need to successfully run Stackspin. If you try to run Stackspin on machines with less than the recommended system requirements, you will notice that some “Pods” (application components) refuse to start.

Stackspin application resource requirements

Application

Memory

CPU cores

Core components

2.8 GiB

1000m

Monitoring

1.5 GiB

180m

Hedgedoc

256 MiB

30m

Nextcloud

2.4 GiB

360m

Velero

625 MiB

20m

Wekan

620 MiB

50m

WordPress

890 MiB

100m

Zulip

2.9 GiB

215m

This guide assumes the VPS’s IP address is 1.2.3.4 and we install on the domain stackspin.example.org. Substitute these two variables with your IP address and the (sub)domain you want Stackpin to be available on.

Step 1: Create cluster configuration

To create a config for your cluster, use the create subcommand of the Stackspin CLI. First, choose a name (we chose stackspin.example.org) for your cluster. Then run the following command to get information about the create subcommand:

$ python -m stackspin stackspin.example.org create --help

Create the initial Stackspin configuration for your VPS by running the following command:

$ python -m stackspin stackspin.example.org create \
  stackspin.example.org \
  --ip-address 1.2.3.4

This configures your cluster under the fully qualified domain name (FQDN) stackspin.example.org. To break down the command:

  • the first, positional argument stackspin.example.org tells the cluster the domain it will be hosted on. This should be a (subdomain of a) domain you own.

  • --ip-address 1.2.3.4 tells the script the IP address of your VPS. This will be used to find the VPS during the installation procedure.

The configuration has now been written to the clusters/stackspin.example.org on your provisioning machine.

Prerequisites

Before you can start, you need the following things:

  1. An API key with Customer rights.

    Read how to get an API key

    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 <#dns-entries>`__ later.
    7. Copy the generated key and run export it to this variable in a terminal:

    Make sure the Stackspin CLI can use your token by storing it in a COSMOS_API_TOKEN variable.

    $ export COSMOS_API_TOKEN=<paste your API key here>

    In the same terminal, you can now use the create subcommand

  2. An SSH key ID from the Cosmos Service Centre’s “VPS Cloud” section. This SSH key will get Root access on the VPS.

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

    • You can also use the API to list ssh keys and find it there. Read the Greenhost API documentation for more information*

  3. The ability to create DNS records that point to the VPS that gets created

Step 1: Create VPS and cluster configuration

We’ll use the create subcommand of the Stackspin CLI to create a VPS and a corresponding configuration file on the provisioning machine.

Here is an example of a complete creation command:

$ python -m stackspin stackspin.example.org create \
  --create-droplet \
  --create-hostname stackspin.example.org \
  --ssh-key-id 112 \
  --create-domain-records \
  --subdomain stackspin \
  example.org

Let’s break down the arguments:

  • --create-droplet: Use the Greenhost API to create a new VPS

  • --create-hostname stackspin.example.org: Create a VPS with hostname stackspin.example.org

  • --ssh-key-id 112: Use SSH key ID 112 (you can find your SSH key ID in the Cosmos Service Centre under VPS Cloud -> Installation SSH Keys. Hover over a button there to see the ID in the URL it uses.

  • --create-domain-records: Use the Greenhost API to create DNS records If you do this, you can skip Step 2: DNS Configuration. The following records are automatically created:

    • An A record stackspin.example.org pointing to the VPS’s IP address

    • A CNAME record *.stackspin.example.org pointing to stackspin.example.org.

  • --subdomain stackspin: Only needed when you use --create-domain-records so the Greenhost API can find your domain. If you use the --subdomain argument, the positional argument must not include the subdomain (i.e., in the example command the positional argument is example.org and not subdomain.example.org).

    If you want to host Stackspin on a root domain, you can omit the subdomain argument.

Step 2: DNS Configuration

You need to configure some DNS records to make Stackspin available over the internet. These DNS records are not optional, because quite a few of them are actually also used by the applications to talk to the other applications (e.g., the single sign-on provider is used by all applications, or Nextcloud embeds ONLYOFFICE).

The following DNS records need to be set for the dashboard and the single sign-on system:

  • An A record dashboard.example.org pointing to the cluster’s IP address,

If you want to guarantee Stackspin will work for all applications you install afterwards, it needs a wildcard DNS record *.example.org that points to your cluster’s IP address.

Advanced Setup

If you do not want to or cannot set a wildcard DNS rule, you will need the following rule:

  • A CNAME record sso.example.org pointing to dashboard.example.org

And similar records for these applications, if you install them:

Monitoring

  • grafana.example.org is used for Grafana, the monitoring dashboard

  • alertmanager.example.org (optional) is used for the Alertmanager dashboard

  • prometheus.example.org (optional) is used for the Prometheus dashboard

Nextcloud and ONLYOFFICE

  • files.example.org is used for Nextcloud

  • office.example.org is used for ONLYOFFICE

Wekan

  • wekan.example.org is used for Wekan

WordPress

  • www.example.org is the default WordPress domain

  • example.org (Optional) – Redirects to www.

Zulip

  • zulip.example.org is used for Zulip

Note

Follow Custom domain names for applications for instructions on using custom domain names.

Step 3: Create Kubernetes cluster

Before you continue, make sure your DNS configuration is propagated. You can do this by making sure ping shows your VPS’s IP address:

$ ping stackspin.example.org
Example output of the command:
PING stackspin.example.org (1.2.3.4) 56(84) bytes of data.
64 bytes from 1.2.3.4 (1.2.3.4): icmp_seq=1 ttl=62 time=9.43 ms
64 bytes from 1.2.3.4 (1.2.3.4): icmp_seq=2 ttl=62 time=52.5 ms
...

If you’ve never logged in to this machine before, you might need to accept the SSH hostkey before you can start the installation process. To be sure, log in to your VPS once before you continue:

$ ssh root@stackspin.example.org

If necessary, check your hostkey fingerprint and type yes to continue. You should get a shell on your VPS. Type exit to quit the shell and continue on your provisioning machine.

Run the install command with the CLI to completely configure your VPS for Stackspin.

$ python -m stackspin stackspin.example.org install

This will take a few minutes. It tries to connect to your VPS as the root user, then installs k3s. In addition it installs command line tools kubectl (Kubernetes cli tool), flux (used for automated updates) and velero (Kubernetes resources and persistent volumes backup) so you can manage the Kubernetes cluster from a shell on the VPS.

Note

It is possible to re-run the install command with a newer version of the installation script. Refer to the Upgrades for details.

Below, we describe how you can install Stackspin on an existing Kubernetes cluster. This process can be followed if you have a “managed Kubernetes” setup, or if you want to use a Kubernetes version other than K3s.

Note

  • Installation on an existing Kubernetes cluster is still experimental and might not work depending on the setup of your cluster/cloud provider. We are happy to receive feedback from your experiences but at the moment we cannot make any guarantees!

Prerequisites

  • A single-node Kubernetes cluster (multi-node support has not been tested by the Stackspin team)

  • A kube_config.yml file for API access

System requirements

The system requirements depend on which applications you want to install into Stackspin. The following table shows the minimum requirements for each application (1000m CPU means 1 core). Sum up the requirements of all the applications you wish to install, together with the “Core components”. That is the amount of memory and CPU you need to successfully run Stackspin. If you try to run Stackspin on machines with less than the recommended system requirements, you will notice that some “Pods” (application components) refuse to start.

Stackspin application resource requirements

Application

Memory

CPU cores

Core components

2.8 GiB

1000m

Monitoring

1.5 GiB

180m

Hedgedoc

256 MiB

30m

Nextcloud

2.4 GiB

360m

Velero

625 MiB

20m

Wekan

620 MiB

50m

WordPress

890 MiB

100m

Zulip

2.9 GiB

215m

Configure DNS

You need to configure some DNS records to make Stackspin available over the internet. These DNS records are not optional, because quite a few of them are actually also used by the applications to talk to the other applications (e.g., the single sign-on provider is used by all applications, or Nextcloud embeds ONLYOFFICE).

The following DNS records need to be set for the dashboard and the single sign-on system:

  • An A record dashboard.example.org pointing to the cluster’s IP address,

If you want to guarantee Stackspin will work for all applications you install afterwards, it needs a wildcard DNS record *.example.org that points to your cluster’s IP address.

Advanced Setup

If you do not want to or cannot set a wildcard DNS rule, you will need the following rule:

  • A CNAME record sso.example.org pointing to dashboard.example.org

And similar records for these applications, if you install them:

Monitoring

  • grafana.example.org is used for Grafana, the monitoring dashboard

  • alertmanager.example.org (optional) is used for the Alertmanager dashboard

  • prometheus.example.org (optional) is used for the Prometheus dashboard

Nextcloud and ONLYOFFICE

  • files.example.org is used for Nextcloud

  • office.example.org is used for ONLYOFFICE

Wekan

  • wekan.example.org is used for Wekan

WordPress

  • www.example.org is the default WordPress domain

  • example.org (Optional) – Redirects to www.

Zulip

  • zulip.example.org is used for Zulip

Note

Follow Custom domain names for applications for instructions on using custom domain names.

Setup

  • Create a directory containing your cluster configuration, i.e. mkdir -p clusters/stackspin.example.org

  • Copy your kube_config.yml file inside your cluster config directory and rename it to kube_config_cluster.yml: cp kube_config.yml clusters/stackspin.example.org/kube_config_cluster.yml

Now that you have a Kubernetes cluster running you can continue to Install Stackspin.