opendesk/docs/getting-started.md

Getting started

This documentation should enable you to create your own evaluation instance of openDesk on your Kubernetes cluster.

• Requirements
• Customize environment
  • DNS
  • Domain
    • Apps
  • Private registries
  • Cluster capabilities
    • Service
    • Networking
    • Ingress
    • Container runtime
    • Volumes
  • Connectivity
    • Ports
      • Web based user interface
      • Mail clients
    • Mail/SMTP configuration
    • TURN configuration
    • Certificate issuer
  • Password seed
  • Install
  • Install single app
  • Install single release/chart
• Access deployment
  • Using from external repository
• Uninstall

Thanks for looking into the openDesk Getting started guide. This documents covers essentials configuration steps to deploy openDesk onto your kubernetes infrastructure.

Requirements

Detailed system requirements are covered on requirements page.

Customize environment

Before deploying openDesk, you have to configure the deployment to suit 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 to create a *.domain.tld A-Record to your cluster ingress controller, otherwise you need to 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.yaml.

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

global:
  hosts:
    nextcloud: "files"

The domain have 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 can be found in helmfile/environments/default/workplace.yaml.

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
Dovecot	dovecot.enabled	true	Mail backend
Element	element.enabled	true	Secure communications platform
Intercom Service	intercom.enabled	true	Cross service data exchange
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 Appsuite	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 for 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 most likely 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 anyway 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 following:

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:

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 choose 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 clusters default ingress.

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

Container runtime

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

cluster:
  container:
    engine: "containerd"

Volumes

When your cluster has a ReadWriteMany volume provisioner, you can benefit from distributed or scaling of apps. By default, only ReadWriteOnce is enabled. To enable ReadWriteMany you can set:

cluster:
  persistence:
    readWriteMany: true

The StorageClass can be set by:

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

Connectivity

Ports

Note: If you use NodePort for service exposure, you need to 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 publicly expose the following ports:

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 which 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 mails.

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

TURN configuration

Some components (Jitsi, Element) use for direct communication a TURN server. 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 with name opendesk-certificates-tls needs to be present in application namespace. For deployment, you can disable 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 single master password via Master Password (algorithm). To prevent others from using your openDesk instance, we highly recommend setting an individual master password via:

export MASTER_PASSWORD="openDesk"

Install

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

helmfile apply -e dev -n <NAMESPACE> [-l <label>] [--suppress-diff]

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 <NAMESPACE> -l component=collabora

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

cd helmfile/apps/collabora
helmfile apply -e dev -n <NAMESPACE>

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 <NAMESPACE> -l name=mariadb

Access deployment

When all apps are successfully deployed and pod status' went to Running or Succeeded, you can navigate to

https://portal.domain.tld

If you change the subdomain of nubus, you need to replace portal by your specified subdomain.

Credentials:

# Replace with your namespace
NAMESPACE=your-namespace

# Get ConfigMap with credentials
kubectl -n ${NAMESPACE} get cm ums-stack-data-swp-data -o jsonpath='{.data.dev-test-users\.yaml}'

Renders you a two part ConfigMap where the username and password attributes in the properties section provide you with the desired information to login with the two default user roles:

Username	Password	Description
default.user	40615..............................e9e2f	Application user
default.admin	17027..............................04db6	Administrator

Using from external repository

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

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

Uninstall

You can uninstall the deployment by:

helmfile destroy -n <NAMESPACE>

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};

Warning

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