Install Stackspin

This guide explains how to install Stackspin on the Kubernetes cluster you have configured in the previous step.

Step 1: Flux configuration

Flux will run inside your Stackspin cluster to install and upgrade applications. It needs to be configured once, using the flux command line tool and scripts provided by us in the Stackspin repository.

Configuration

Copy the file install/.flux.env.example to your cluster dir clusters/stackspin.example.org/.flux.env. This file contains the last bit of information you need to configure. Make sure not to put any quotes around your values, because that can make the resulting yaml files invalid. Also, using a dollar sign $ or double quote " may lead to problems, so please avoid using those characters in the values.

Cluster information

# The IP address of your cluster
ip_address=1.2.3.4
# The FQDN of your cluster
domain=stackspin.example.org
# The system administrator's email address. Alerts are sent to this address
admin_email=admin@example.org

Outgoing email

Stackspin uses SMTP to send emails. This is essential for finishing account setups with password recovery links. Additionally, apps like Nextcloud, Zulip and Wordpress will be able to send email notifications from the email address configured here. You also may receive alert notification emails from Stackspin’s monitoring system. See Email alerts for more information about those alerts, especially during installation.

Because Stackspin does not include an email server, you need to obtain SMTP configuration details from your (external) email provider.

Note

You have some freedom in choosing the “from” address that’s used for all outgoing emails. However, you’ll need to meet some requirements so that the SMTP server you submit to and the recipient’s mail server will accept the email:

  • If the domain of the “from” address is not served by the SMTP server you submit to, typically it will try to verify that the “from” address is an existing address. This holds at least for Greenhost mail servers.

  • Some recipient mail servers require that SPF records are set for the domain of the “from” address – and then of course that those SPF records include the Stackspin machine as allowed sender.

Backups with Velero (Optional)

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 resources in your cluster; 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, Zulip 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 Stackspin, like programs installed via apt, or data added to the VPS disk not through Stackspin.

To configure Velero, edit the file .flux.env, and configure the settings with the backup_s3_ prefix.

Then continue with the installation procedure as described below. At the end of the installation procedure, you have to install the velero application.

For information on how to use Velero with Stackspin, please see Backup.

Step 2: Install core applications

Before you can start, you need to execute a few commands from the installation directory on your provisioning machine. Don’t forget to replace stackspin.example.org with your domain.

We will use this variable in the following commands, set it to your cluster directory.

$ export CLUSTER_DIR=$PWD/clusters/stackspin.example.org

Make sure your virtualenv is activated.

$ . env/bin/activate

Copy the installation kustomization to your cluster directory.

$ cp install/kustomization.yaml $CLUSTER_DIR/

Tell kubectl to use your cluster’s kube_config.

$ export KUBECONFIG=$CLUSTER_DIR/kube_config_cluster.yml

Ensure flux-system namespace is created.

$ kubectl get namespace flux-system 2>/dev/null || kubectl create namespace flux-system

This inserts the configuration from .flux.env into your cluster as a “secret”.

$ kubectl apply -k $CLUSTER_DIR

After you have executed that code, your terminal should show:

secret/stackspin-cluster-variables created

Next, run:

$ ./install/install-stackspin.sh

This installs the core of Stackspin into your cluster. To see what’s included, check the flux2/core/base folder in the git repository.

You can run the following command to view the status of the installation of all components:

$ watch flux get kustomization

Step 3: Install additional applications

After the script has completed, and the dashboard kustomization shows as “Ready” in the flux get kustomization command, you can use the Dashboard CLI to install applications.

  • Monitoring stack (Prometheus, Grafana) kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install monitoring

  • Nextcloud and Onlyoffice with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install nextcloud

  • Zulip chat with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install zulip

  • Wekan with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install wekan

  • WordPress with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install wordpress

  • Velero with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install velero (only if you have configured it in Backups with Velero (Optional)).

  • HedgeDoc with kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app install hedgedoc

When the command completes, the application installation may still be running on the Stackspin cluster. You can monitor the progress by running kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app status <app_name>

Warning

To remove an app, you can run a similar command, see below. Note though that this will also remove all data that belongs to the application! For example, for Nextcloud that includes removing all uploaded files and metadata, as well as other data like calendar events, etc.

kubectl exec -n stackspin deploy/dashboard-backend -- flask cli app uninstall $appToRemove

Step 4: Validate setup

Once the installation has been completed, you can log in on https://dashboard.stackspin.example.org (as always: replace stackspin.example.org with your domain). To get your login details, run:

$ python -m stackspin stackspin.example.org admin-credentials

Additionally, because Stackspin is still under development, we would like you to follow our Test your installation to make sure that the setup process went well.

Step 5: Let us know!

We would love to hear about your experience installing Stackspin. If you encountered any problems, please create an issue in our issue tracker. If you didn’t please still reach out as described on our contact page and tell us how you like Stackspin so far. We want to be in communication with our users, and we want to help you if you run into problems.