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.
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:
An API key with Customer rights.
Read how to get an API key
- In the Cosmos service centre, click your webmaster account name on the top right corner
- Go to "User settings"
- Click "API keys"
- Click "New API key"
- Click "Generate new key"
- 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.
- 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
subcommandAn 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*
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 hostnamestackspin.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
recordstackspin.example.org
pointing to the VPS’s IP addressA
CNAME
record*.stackspin.example.org
pointing tostackspin.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 isexample.org
and notsubdomain.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
recorddashboard.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
recordsso.example.org
pointing todashboard.example.org
And similar records for these applications, if you install them:
- Monitoring
grafana.example.org
is used for Grafana, the monitoring dashboardalertmanager.example.org
(optional) is used for the Alertmanager dashboardprometheus.example.org
(optional) is used for the Prometheus dashboard
- Nextcloud and ONLYOFFICE
files.example.org
is used for Nextcloudoffice.example.org
is used for ONLYOFFICE
- Wekan
wekan.example.org
is used for Wekan
- WordPress
www.example.org
is the default WordPress domainexample.org
(Optional) – Redirects towww.
- 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.
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
recorddashboard.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
recordsso.example.org
pointing todashboard.example.org
And similar records for these applications, if you install them:
- Monitoring
grafana.example.org
is used for Grafana, the monitoring dashboardalertmanager.example.org
(optional) is used for the Alertmanager dashboardprometheus.example.org
(optional) is used for the Prometheus dashboard
- Nextcloud and ONLYOFFICE
files.example.org
is used for Nextcloudoffice.example.org
is used for ONLYOFFICE
- Wekan
wekan.example.org
is used for Wekan
- WordPress
www.example.org
is the default WordPress domainexample.org
(Optional) – Redirects towww.
- 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 tokube_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.