Skip to content

By default this will deploy a local k3s instance, but the templates should be compatible with any kubernetes distribution.

The default deployment will be completely self-contained, special care will need to be taken if external services are integrated (such as an existing mysql instance).

Getting started

Requirements

  • bash (from your distro)
  • openssl (from your distro)
  • uuidgen (from your distro)
  • yq: (from your distro or via wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq && chmod +x /usr/local/bin/yq)
  • helm: https://helm.sh/docs/intro/install/

K3s requirements

  • k3s requirements: https://docs.k3s.io/installation/requirements
  • disabled firewall (systemctl stop firewalld, I suppose it's possible to configure the firewall properly, but by default your cluster will fail in all sorts of interesting ways that are hard to troubleshoot.)
  • DNS resolution between nodes must be available (e.g. between server and worker nodes).
  • stop conflicting docker deployments that are using the same ports
  • Make sure k3s is installed in a location that can be found via sudo, so sudo k3s works (Not always given when installed into /usr/local/bin)

Infrastructure requirements

  • For a publicly available non-clustered k3s deployment one public ip is required. ** It is important that the IP is public, and not behind a proxy, because of requirements such as seeing the client-ip. Without a public IP features such as email sending/receiving and webrtc will not function. ** It is possible to run kolab behind e.g. haproxy by using multiple internal ip's and metallb (see openshift deployment).

Quickstart

To just deploy a k3s deployment locally, run this:

./kolabctl configure
./kolabctl deploy --k3s

This will generate a values.yaml file, install k3s and the required dependencies and deploy kolab on k3s.

kolabctl

The local deployment can be managed using kolabctl which simplifies various administrative tasks.

kolabctl is a thin wrapper around helm/kubectl/artisan, so it is not required to use kolabctl if you are more familiar with the underlying tools, but it illustrates the various tasks.

Deployment

Configure

The deployment configuration is entirely contained in the values.yaml file.

To generate an initial values.yaml file:

./kolabctl configure

you can pass in all requested values like so:

env PUBLIC_IP=1.2.3.4 DOMAIN=kolab.local ADMIN_PASSWORD=simple123 ./kolabctl configure

Adjust the values as desired before deploying, but please note that you can easily break the deployment by deviating from the defaults.

The following values are required during setup:

  • DOMAIN: The public domain for the deployment, e.g. kolab.local
  • PUBLIC_IP: Public ip of the deployment
  • ADMIN_PASSWORD: The password that will be set for the admin@$DOMAIN user

Other values can be adjusted in the values.yaml file before deployment, and generated secrets can be inspected inside the values.yaml file.

Configure for Openshift

The openshift deployment currently expects:

  • Non-http services are exposes via metallb
  • The certificate is separately provisioned to a secret called kolab-secret

To configure:

env PUBLIC_IP=185.254.79.13 DOMAIN=kolab.apheleia-it.ch ADMIN_PASSWORD=simple123 POSTFIX_LOADBALANCER_IP=10.11.2.137 PROXY_LOADBALANCER_IP=10.11.2.138 MEET_LOADBALANCER_IP=10.11.2.139 METALLB_ADDRESS_POOL=vlan1102-l2 STORAGE_CLASS=ocs-storagecluster-cephfs ./kolabctl configure --openshift

Deploy on Kubernetes

./kolabctl deploy

This will deploy Kolab via helm and kubectl on the currently connected cluster. Once the command completes, run

./kolabctl selfcheck

to validate that the deployment was successful.

Deploy including k3s

./kolabctl deploy --k3s

This will first install k3s locally, configure it and install helm. Next helm will login to the registry and the kolab images will be pulled from the registry. Finally, kolab is deployed in the new k3s instance.

Updating

To apply the latest changes from your local values.yaml with the latest chart changes, run:

./kolabctl update