A guide to hosting openDesk on K3s

Digital sovereignty via self-hosting

Beyond public administration, many organisations and individual users are interested in reducing their dependencies on corporate software giants. Open-source software solutions offer precisely this independence thanks to their transparency and accessibility, and openDesk was developed to enable this level of autonomy as a versatile office and collaboration suite.

One way to use openDesk is through self-hosting in a local environment. By combining openDesk with K3s, even smaller organisations and private users can create their own sovereign, privacy-friendly digital working environment.

This guide provides step-by-step instructions for installing openDesk on a K3s Kubernetes cluster. As a lean, relatively easy-to-set-up Kubernetes distribution, K3s is well suited to environments with limited resources.

Please note that basic knowledge of Kubernetes and the command line is helpful for following this guide.

1. Prerequisites

Before you start installing openDesk, please ensure that your environment meets the following requirements.

1.1 openDesk requirements

openDesk has specific requirements for the Kubernetes cluster and supporting infrastructure, most notably:

• An existing Kubernetes (K8s) cluster with version >= v1.24 is required. It needs to be a CNCF Certified Kubernetes distribution. K3s fulfils this requirement, as it is a certified distribution.

• You'll need a domain and a configured DNS service to make openDesk accessible. openDesk is designed so that each application or service is provided under a dedicated subdomain. We recommend creating a *.your-domain.tld A-record as well as a your-domain.tld A-record for your cluster ingress controller.

• An ingress controller is required to forward external traffic to the openDesk services within the cluster. openDesk supports the Ingress NGINX Controller, version >= 4.11.5/1.11.5. Ensuring compatibility with openDesk requires certain configurations to be made for the Ingress NGINX Controller. In particular, controller.allowSnippetAnnotations=true and
  controller.admissionWebhooks.allowSnippetAnnotations=true, since openDesk components use snippet annotations.

Important note for Ingress NGINX >= 1.12.0:

With the release of Ingress NGINX 1.12.0, new security default settings have been introduced that are incompatible with current openDesk versions. If you want to use Ingress NGINX >= 1.12.0, the following settings must be set:

controller.config.annotations-risk-level=Critical
controller.config.strict-validate-path-type=false

Also make sure that you install Ingress NGINX 1.11.5 or 1.12.1, as earlier versions may have security issues.

• Helm is a package manager for Kubernetes and is used to deploy openDesk components. You'll need Helm version >= v3.9.0, but not v3.18.0 (due to a known bug). Versions newer than v3.17.3 should also work, but we have only tested up to version v3.17.3.

• Helmfile is a declarative specification system for the provision of Helm releases. It is used to configure and templatise openDesk's 35+ Helm charts. You'll need Helmfile version >= v1.0.0.

• HelmDiff is required by Helmfile to compare the desired state with the provided state. You'll need HelmDiff version >= v3.11.0.

• openDesk requires a volume provisioner that supports ReadWriteOnce (RWO). For local deployments, a local or hostPath provisioner is sufficient. Note that some components may require a ReadWriteMany (RWX) volume provisioner for distributed mode or horizontal scaling.

• A certificate manager (e.g. cert-manager) that manages TLS certificates for your domain is required. If you use cert-manager, it has to be installed with its special Kubernetes definitions (CRDs) before deploying openDesk.

• In single node configurations you may run into errors with Inotify file watches, which should be mitigatable by applying $ sudo sysctl -w fs.inotify.max_user_instances=10000000 .

1.2 Minimum hardware requirements for self-hosting openDesk

The following minimum requirements are intended for an initial evaluative deployment of openDesk. Higher specifications are recommended for production environments:

1.3 External services (recommended for production)

Some services are bundled for the development and evaluation of openDesk. For production deployments, however, you should use your own production-ready services. Recommended external services:

2. Preparation of K3s

K3s is an excellent choice for openDesk because it's lightweight and easy to install. By default though, K3s installs Traefik as the ingress controller. Since openDesk prefers the NGINX ingress controller, you'll need to disable Traefik.

2.1 K3s installation without Traefik

If you're reinstalling K3s, you can deactivate Traefik directly during the installation. To do this, use the --disable=traefik flag:

$ curl -sfL https://get.k3s.io | sh -s -- --disable=traefik

Alternatively, you can install K3s using the k3sup helper tool:

$ k3sup install --cluster --host <host IP> --user <host user> --k3s-channel stable --k3s-extra-args '--disable traefik'

2.2 Disable Traefik in an existing K3s installation

If you already have a K3s installation with Traefik enabled, you can disable the latter. The simplest method is to restart the K3s server with the --disable=traefik flag.

You can also remove the Traefik manifests manually:

$ sudo rm -rf /var/lib/rancher/k3s/server/manifests/traefik.yaml

You'll then need to restart K3s:

$ sudo systemctl restart k3s

2.3 Install the NGINX ingress controller

Once Traefik is deactivated, you can install the NGINX ingress controller. We recommended using the official Helm chart. Make sure you install the version that's compatible with the openDesk requirements (>= 4.11.5/1.11.5).

Add the Helm repository for the NGINX ingress controller:

$ helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
$ helm repo update

Install the NGINX ingress controller with the required snippet annotations and customised security settings:

$ helm install ingress-nginx ingress-nginx/ingress-nginx \
--create-namespace \
--namespace ingress-nginx \
--set controller.allowSnippetAnnotations=true \
--set controller.admissionWebhooks.allowSnippetAnnotations=true \
--set controller.config.annotations-risk-level=Critical \
--set controller.config.strict-validate-path-type=false

Check whether the ingress controller has been successfully deployed:

$ kubectl get pods -n ingress-nginx

2.4 Install cert-manager and set up the Let's Encrypt ClusterIssuer

openDesk requires SSL certificates for your-domain.tld. The easiest way for this is to use Let's Encrypt. In the following, the cert-manager is installed and a ClusterIssuer for Let's Encrypt is set up. openDesk then requests and installs the required SSL certificates totally automatically.

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.18.2/cert-manager.yaml

Create the file clusterissuer.yaml with the following content. Enter your email address in the email field to get notifications about expiring certificates:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer # I'm using ClusterIssuer here
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: <ihre-email@ihre-email-domain.tld>
privateKeySecretRef:
name: letsencrypt-prod
solvers:
- http01:
ingress:
class: nginx

Now install the ClusterIssuer in the cluster:

$ kubectl apply -f clusterissuer.yaml

2.5 Set up Volume Provisioner

For local deployments, the Local Path Provisioner can be used. It supports RWO and creates PVs dynamically on the host filesystem.

$ kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.32/deploy/local-path-storage.yaml
$ kubectl patch storageclass local-path -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

3. Deploying openDesk

The deployment of openDesk is done via Helmfile, which makes it easier to manage openDesk's numerous Helm charts.

3.1 Cloning the repository

Clone the openDesk deployment repository from GitLab:

$ export OPENDESK_RELEASE="v1.11.0"
$ git clone -b $OPENDESK_RELEASE
$ git clone https://gitlab.opencode.de/bmi/opendesk/deployment/opendesk.git
$ cd opendesk

3.2 Customising the environment

Now the deployment needs to be customised to your environment. To make updates easy, we recommend doing this in a dedicated environment (e.g. dev, test or prod ) instead of directly in the default environment files.

Create a values.yaml.gotmpl file for your environment. For these instructions we use dev:

$ touch helmfile/environments/dev/values.yaml.gotmpl

Edit the helmfile/environments/dev/values.yaml.gotmpl file to configure your domain and other specific settings. The most important settings are:

• Domain: Set your domain under global.domain. Example:
  
  global:
domain: "your-domain.tld"
  
  Alternatively, you can also set the domain via an environment variable:
  
  bash export DOMAIN=your-domain.tld
  
  

• Apps: You can enable or disable certain openDesk applications by adjusting the apps.yourAppName.enabled values in this file. A list of all available apps and their default values can be found under helmfile/environments/default/opendesk_main.yaml.gotmpl.

  
  An example for deactivating Jitsi:

  apps:
jitsi:
enabled: false

• Cluster capabilities: Configure the service type(NodePort, LoadBalancer or ClusterIP) for openDesk applications that require external connections (e.g. Jitsi, Dovecot).
  
  cluster:
service:
type: "NodePort"
  
  

• Ingress Class Name: If your ingress controller is not the default ingress controller in your cluster, you can customise the ingressClassName:
  
  ingress:
ingressClassName:
"ingress-nginx"
  
  Otherwise, please use the following setting:
  
  ingress:
ingressClassName: "nginx"


  
  

• Certificates: Finally, point openDesk to the cert-manager ClusterIssuer from the previous step:
  
  certificate:
issuerRef:
name: "letsencrypt-prod"

  
  
  The complete helmfile/environments/dev/values.yaml.gotmpl file then looks like this:
  
  

  global:
domain: "your-domain.tld"

cluster:
service:
type: "NodePort"

ingress:
ingressClassName: "nginx"

certificate:
issuerRef:
name: "letsencrypt-prod"

3.3 Deploying

Once you've configured the environment, openDesk can be deployed with Helmfile. Make sure that you're in the opendesk directory you previously cloned.

Before we deploy, we create a dedicated Kubernetes namespace to deploy to and make this the current default.

$ export OPENDESK_NAMESPACE="opendesk"
$ kubectl create namespace ${OPENDESK_NAMESPACE}
$ kubectl config set-context --current --namespace=${OPENDESK_NAMESPACE}

Now, we can deploy openDesk to this namespace.

$ helmfile apply --environment dev --namespace ${OPENDESK_NAMESPACE}

This command will deploy all required Helm charts and install the openDesk applications in your K3s cluster. The process may take some time.

4. Checking deployment

After deployment, you can check the status of the openDesk pods and services:

$ kubectl get pods -A
$ kubectlget svc -A
$ kubectlget ingress -A

All pods should have the status Running and the ingress resources should be configured correctly and point to your domain.

5. Accessing openDesk

Great! You've now installed openDesk on your K3s cluster. Once all the services are up and running and the DNS entry has been correctly set, you'll be able to access openDesk via your configured domain in your web browser.

openDesk is installed with an administrator account. You can issue the password in the cluster as follows:

$ kubectl get secret ums-nubus-credentials -o jsonpath='{.data.administrator_password}' | base64 -d

Self-hosting provides a secure basis for your daily office and collaboration apps, and it allows you to enjoy the key benefits of open source software solutions: transparency, flexibility and the ability to create an independent working environment.

For more detailed instructions and further technical information, visit our official documentation at GitLab.