Customizing

In this guide we show how to customize your cluster installation, i.e. if you want to install additional applications, or change the configuration of extisting apps installed by Stackspin this is the right place. Customizing other parts of your cluster is possible but not yet covered by this guide. This guide is written for users with advanced knowledge of the tools behind Stackspin, most importantly: Kubernetes, Helm and Flux.

Warning

Customizing your Stackspin cluster could break your cluster in a way that’s not easy to recover from. Please be aware of the potential risk when proceeding.

Prerequisites

A functional Stackspin cluster installed following the Stackspin installation instructions

Customize Stackspin applications

Apps deployed by Stackspin are configured using helm values from templates in flux2/apps/<application>/release.yaml. It is possible to override values from the helmrelease by adding a custom ConfigMap or Secret to the cluster. The secret or configmap name is specified in the valuesFrom section of the release.yaml file. Read more in the Flux documentation

Example: Customize Nextcloud to work with staging certificates

Our CI pipeline works with staging certificates from Let’s Encrypt, for that reason we need to allow insecure connections for the integration with ONLYOFFICE. You can find the file at install/overrides/stackspin-nextcloud-override.yaml.

To apply it, run the following commands:

If you want to run this on your provisioning machine, tell kubectl to use your cluster:

$ export KUBECONFIG=$PWD/clusters/stackspin.example.org/kube_config_cluster.yml

Check the current state of the helmrelease you want to modify:

$ flux get helmrelease -A

If all is OK, make sure to apply your override configmap or secret in the same namespace as your helmrelease with the ‘-n’ argument

$ kubectl apply \
  -n stackspin-apps \
  -f ./install/overrides/stackspin-nextcloud-override.yaml

Custom dashboard styling

It’s possible to change the appearance of the Stackspin dashboard, choosing custom colours, logo and background picture. To do so:

Create a PVC called dashboard-overlay in the stackspin namespace.
Set the helm value overlay of the dashboard to true (using a helm value override as explained above) and reconcile the HelmRelease to let the change take effect.
Copy your custom files to the PVC. Any files you add will be served from the dashboard frontend and files existing in the docker image are shadowed by this overlay, so this way you can change basically anything. As a convenient entrypoint, the dashboard loads a stylesheet called /custom/style/custom.css so creating that file should automatically apply your styling.

Here’s an example custom.css to get you started:

:root {
    --colour-primary-50: #F2F4FC;
    --colour-primary-100: #E1E6F8;
    --colour-primary-200: #CAD3F3;
    --colour-primary-300: #A6B7EA;
    --colour-primary-400: #7C92DE;
    --colour-primary-500: #5D70D4;
    --colour-primary-600: #525DCA;
    --colour-primary-700: #3F44B6;
    --colour-primary-800: #383995;
    --colour-primary-900: #323476;
    --colour-primary-950: #222249;
    --colour-primary-light: #525DCA;
    --colour-primary-default: #525DCA;
    --colour-primary-dark: #323476;
    --stackspin-logo: url('/custom/logo.svg');
    --stackspin-background: url('/custom/background.webp');
}

.stackspin-logo {
  content: var(--stackspin-logo);
  width: 151px;
  height: 54px;
}

.stackspin-background {
  background-image: var(--stackspin-background);
  background-repeat: no-repeat;
  background-size: cover;
}

Custom flux repository

Stackspin uses Flux to install and auto-update applications. If Customize Stackspin applications is not enough and you need more advanced customization, i.e. to install extra applications or other things into the Kubernetes cluster, our advice would be to set up your own custom Flux git repository.

Please refer to the Stackspin Flux example and the Flux 2 documentation for more information.

Adding custom apps to the cluster

When you do this, you are fully responsible for keeping those applications secure and updated. If any of those applications is insecure, that can also invalidate the security of your Stackspin applications, because they are part of the same cluster and VPS.

Please follow our Gitlab issue template for adding new apps. Not all steps are needed if you only want to add a new app to your cluster though (see the template for details). If you intend to contribute to Stackspin with a new app merge request please make sure to check all boxes.

Custom domain names for applications

It is possible to override the default domain names we have defined for the applications. In the future, it should be possible to do that through the dashboard, but currently you need to get your hands dirty inside the Kubernetes cluster.

To change an application’s domain name, you need an already running and installed Stackspin cluster. After you have installed the Stackspin core, you can continue.

If you haven’t already, create a DNS record for your desired domain that points to your cluster’s IP address.
Create a configmap called stackspin-<app>-kustomization-variables in the flux-system namespace. Set an <app>_domain key in the configmap with value your desired domain. Note that that is used as the full domain name, not just the subdomain. Some applications have multiple associated domains; to check the possibilities, view the contents of the stackspin-<app>-kustomization-defaults. You only need to include entries that you wish to change from those defaults.

If you did not install the application yet, follow Step 3: Install additional applications to install the application to the custom domain.

If you have already installed the application, you need to “reconcile” the kustomization and the helmrelease that correspond to it. Execute the following commands in order:

$ flux reconcile kustomization <app>

$ flux reconcile helmrelease -n stackspin-apps <app>

Note that if you’re changing the domain for Grafana, the last command needs to run in the stackspin namespace rather than stackspin-apps.

Note

Some applications may need some further action to activate the change; for example Hedgedoc needs to restart:

$ kubectl rollout restart deploy -n stackspin-apps hedgedoc

Nextcloud stores the external hostname in its trusted_domains config value (along with localhost), and the provisioning built into the Nextcloud docker container does not attempt to change an existing value, so we need to change that manually:

$ kubectl exec -it -n stackspin-apps deploy/nc-nextcloud -- su -s /bin/bash www-data
(nc-shell)$ php occ config:system:set trusted_domains 1 --value=$NEW_NC_DOMAIN

Until you’ve made this change, the Nextcloud pod’s readiness probe gets a 400 error, so the pod is considered unhealthy and will be automatically restarted from time to time.