Zum Inhalt springen
openDesk Hilfe

Getting Started

This documentation lets you create an openDesk evaluation instance on your Kubernetes cluster.

Thanks for looking into the openDesk Getting Started guide. This document covers essential configuration steps to deploy openDesk onto your Kubernetes infrastructure.

Requirements

Detailed system requirements are covered on the requirements page.

Customize environment

Before deploying openDesk, you must configure the deployment to fit your environment. To keep your deployment up to date, we recommend customizing in dev, test, or prod and not in default environment files.

All configuration options and their default values can be found in files at helmfile/environments/default/

For the following guide, we will use dev as environment where variables can be set in helmfile/environments/dev/values.yaml.gotmpl.

DNS

The deployment is designed to deploy each application/service under a dedicated subdomain. For your convenience, we recommend creating a *.domain.tld A-Record to your cluster ingress controller; otherwise, you must create an A-Record for each subdomain.

Record name Type Value Additional information
*.domain.tld A IPv4 address of your Ingress Controller
*.domain.tld AAAA IPv6 address of your Ingress Controller
mail.domain.tld A IPv4 address of your postfix NodePort/LoadBalancer Optional mail should directly be delivered to openDesk’s Postfix
mail.domain.tld AAAA IPv6 address of your postfix NodePort/LoadBalancer Optional mail should directly be delivered to openDesk’s Postfix
domain.tld MX 10 mail.domain.tld
domain.tld TXT v=spf1 +a +mx +a:mail.domain.tld ~all Optional, use proper MTA record if present
_dmarc.domain.tld TXT v=DMARC1; p=quarantine Optional
default._domainkey.domain.tld TXT v=DKIM1; k=rsa; h=sha256; ... Optional DKIM settings

Domain

A list of all subdomains can be found in helmfile/environments/default/global.gotmpl.

All subdomains can be customized. For example, Nextcloud can be changed to files.domain.tld in dev environment:

global:
  hosts:
    nextcloud: "files"

The domain has to be set either via dev environment

global:
  domain: "domain.tld"

or via environment variable

export DOMAIN=domain.tld

Apps

All available apps and their default value are in helmfile/environments/default/opendesk_main.gotmpl.

Component Name Default Description
Certificates certificates.enabled true TLS certificates
ClamAV (Distributed) clamavDistributed.enabled false Antivirus engine
ClamAV (Simple) clamavSimple.enabled true Antivirus engine
Collabora collabora.enabled true Weboffice
CryptPad cryptpad.enabled true Weboffice
dkimpy dkimpy.enabled false Postfix milter for DKIM
Dovecot dovecot.enabled true Mail backend
Element element.enabled true Secure communications platform
Home home.enabled true Base domain portal redirect
Jitsi jitsi.enabled true Videoconferencing
MariaDB mariadb.enabled true Database
Memcached memcached.enabled true Cache Database
MinIO minio.enabled true Object Storage
Nextcloud nextcloud.enabled true File share
Nubus nubus.enabled true Identity Management & Portal
OpenProject openproject.enabled true Project management
OX App Suite oxAppSuite.enabled true Groupware
Postfix postfix.enabled true MTA
PostgreSQL postgresql.enabled true Database
Redis redis.enabled true Cache Database
XWiki xwiki.enabled true Knowledge management

Exemplary, Jitsi can be disabled like:

jitsi:
  enabled: false

Private registries

By default, Helm charts and container images are fetched from OCI registries. These registries can be found in most cases in the openDesk/component section on Open CoDE.

For untouched upstream artifacts that do not belong to a functional component's core, we use upstream registries like Docker Hub.

Doing a test deployment will be fine with this setup. In case you want to deploy multiple times a day and fetch from the same IP address, you might run into rate limits at Docker Hub. In that case and in cases you prefer the use of a private image registry, you can configure such for your target environment by setting

  • global.imageRegistry for a private image registry and
  • global.helmRegistry for a private Helm chart registry.
global:
  imageRegistry: "my_private_registry.domain.tld"

alternatively, you can use an environment variable:

export PRIVATE_IMAGE_REGISTRY_URL=my_private_registry.domain.tld

or control repository override fine-granular per registry:

repositories:
  image:
    dockerHub: "my_private_registry.domain.tld/docker.io/"
    registryOpencodeDe: "my_private_registry.domain.tld/registry.opencode.de/"

If authentication is required, you can reference imagePullSecrets as follows:

global:
  imagePullSecrets:
    - "external-registry"

Cluster capabilities

Service

Some apps, like Jitsi or Dovecot, require HTTP and external TCP connections. These apps create a Kubernetes service object. You can configure whether NodePort (for on-premise), LoadBalancer (for cloud), or ClusterIP (to disable) should be used:

cluster:
  service:
    type: "NodePort"

Networking

If your cluster has not the default cluster.local domain configured, you need to provide the domain via:

cluster:
  networking:
    domain: "acme.internal"

If your cluster has not the default 10.0.0.0/8 CIDR configured, you need to provide the CIDR via the following:

cluster:
  networking:
    cidr:
      - "127.0.0.0/8"

If your load balancer / reverse proxy IPs are not already covered by the above cidr you need to explicitly configure the related IPs or IP ranges:

cluster:
  networking:
    incomingCIDR:
      - "172.16.0.0/12"

Ingress

By default, the ingressClassName is empty to select your default ingress controller. You may want to customize it by setting the following attribute to the name of the currently only supported ingress controller ingress-nginx (see requirements.md) for reference) within your deployment if that is not the cluster’s default ingress.

ingress:
  ingressClassName: "name-of-my-nginx-ingress"

Container runtime

Some apps require specific configurations for the container runtime. You can set your container runtime like cri-o, containerd or docker by:

cluster:
  container:
    engine: "containerd"

Volumes

The StorageClass must be set by:

persistence:
  storageClassNames:
    RWX: "my-read-write-many-class"
    RWO: "my-read-write-once-class"

RWX is optional and requires that your cluster has a ReadWriteMany volume provisioner. If you can make use of it it benefits the distribution or scaling of apps. By default, only ReadWriteOnce is enabled. To enable ReadWriteMany you have to set:

cluster:
  persistence:
    readWriteMany: true

Connectivity

Ports

Note: If you use NodePort for service exposure, you must check your deployment for the actual ports.

Web-based user interface

To use the openDesk functionality with its web-based user interface, you need to expose the following ports publicly:

Component Description Port Type
openDesk Kubernetes Ingress 80 TCP
openDesk Kubernetes Ingress 443 TCP
Jitsi Video Bridge ICE Port for video data 10000 UDP
Mail clients

To connect with mail clients like Thunderbird, the following ports need public exposure:

Component Description Port Type
Dovecot IMAPS 993 TCP
POP3S 995 TCP
Postfix SMTP 25 TCP
SMTPS 587 TCP

Mail/SMTP configuration

To use the full potential of the openDesk, you need to set up an SMTP relay that allows sending emails from the whole subdomain.

smtp:
  host: "mail.open.desk"
  username: "openDesk"
  password: "secret"

Enabling DKIM signing of emails helps to reduce spam and increases trust. openDesk ships dkimpy-milter as Postfix milter for signing emails.

dkimpy:
  enable: true
  dkim:
    key:
      value: "HzZs08QF1O7UiAkcM9T3U7rePPECtSFvWZIvyKqdg8E="
    selector: "default"
    useED25519: true # when false, RSA is used

TURN configuration

Some components (Jitsi, Element) use a TURN server for direct communication. You can configure your own TURN server with these options:

turn:
  transport: "udp" # or tcp
  credentials: "secret"
  server:
    host: "turn.open.desk"
    port: "3478"
  tls:
    host: "turns.open.desk"
    port: "5349"

Certificate issuer

As mentioned in requirements, you can provide your own valid certificate. A TLS secret named opendesk-certificates-tls must be present in the application namespace. For deployment, you can turn off Certificate resource creation by:

certificates:
  enabled: false

If you want to leverage the cert-manager.io to handle certificates, like Let's encrypt, you need to provide the configured cluster issuer:

certificate:
  issuerRef:
    name: "letsencrypt-prod"

Additionally, it is possible to request wildcard certificates by:

certificate:
  wildcard: true

Password seed

All secrets are generated from a master password via Master Password (algorithm). To prevent others from using your openDesk instance, you must set your individual master password via:

export MASTER_PASSWORD="your_individual_master_password"

Install

After setting your environment-specific values in dev environment, you can start deployment by:

helmfile apply -e dev -n  [-l

Arguments:

  • -e <env>: Environment name out of default, dev, test, prod
  • -n <namespace>: Kubernetes namespace
  • -l <label>: Label selector
  • --suppress-diff: Disable diff printing

Install single app

You can also install or upgrade only a single app like Collabora, either by label selector:

helmfile apply -e dev -n  -l component=collabora

or by switching into the apps' directory (faster):

cd helmfile/apps/collabora
helmfile apply -e dev -n

Install single release/chart

Instead of iteration through all services, you can also deploy a single release like mariadb by:

helmfile apply -e dev -n  -l name=mariadb

Access deployment

When all apps are successfully deployed, and their Pod's status is Running or Succeeded, you can navigate to

https://portal.domain.tld

If you change the subdomain of nubus, you must replace portal with the specified subdomain.

Credentials:

openDesk deploys with the standard user account Administrator, which password you get retrieved as follows:

## Set your namespace
NAMESPACE=

## Get password for IAM "Administrator" account
kubectl -n ${NAMESPACE} get secret ums-nubus-credentials -o jsonpath='{.data.administrator_password}' | base64 -d

Using the aforementioned account, you can either create new accounts manually or make use of the openDesk User Importer script or container.

For example you get a default and default-admin account by running the following snippet, after settings the appropriate values in the first three lines.

ADMINISTRATOR_PASSWORD=
DOMAIN=
DEFAULT_USERS_PASSWORD=
docker run --rm registry.opencode.de/bmi/opendesk/components/platform-development/images/user-import:3.0.0 \
  ./user_import_udm_rest_api.py \
    --import_domain ${DOMAIN} \
    --udm_api_password ${ADMINISTRATOR_PASSWORD} \
    --set_default_password ${DEFAULT_USERS_PASSWORD} \
    --import_filename template.ods \
    --create_admin_accounts True

Using from external repository

Referring to ./helmfile_generic.yaml.gotmpl from an external directory or repository is possible. The helmfile.yaml.gotmpl that refers to ./helmfile_generic.yaml.gotmpl may define custom environments. These custom environments may overwrite specific configuration values. These configuration values are:

  • global.domain
  • global.helmRegistry
  • global.master_password

Uninstall

You can uninstall the deployment by:

helmfile destroy -n

Note
Not all Jobs, PersistentVolumeClaims, or Certificates are deleted; you have to delete them manually

'Sledgehammer destroy' - for fast development turn-around times (at your own risk):

NAMESPACE=your-namespace

## Uninstall all Helm charts
for OPENDESK_RELEASE in $(helm ls -n ${NAMESPACE} -aq); do
  helm uninstall -n ${NAMESPACE} ${OPENDESK_RELEASE};
done

## Delete leftover resources
kubectl delete pvc --all --namespace ${NAMESPACE};
kubectl delete jobs --all --namespace ${NAMESPACE};
kubectl delete configmaps --all --namespace ${NAMESPACE};

Warning
Without specifying or empty --namespace flag, cluster-wide components get deleted!