HCL Domino

Latest chart version:

chartVersion: "1.13.2"

Custom chart for deploying an HCL Domino server cluster on Kubernetes using StatefulSets.

Architecture

Each Domino server is a separate StatefulSet with its own PVC and Service. Servers are grouped by role (type):

Optionally, each pod runs a Grafana Alloy sidecar that ships notes.log, domino-keep.log, and Traveler logs (NTSAudit, NTSErrors, NTSUsage, NTSActivity) to Loki (enabled via alloy.enabled: true in environment values).

Each pod runs two init containers before Domino starts: - fix-data-dir — fixes PVC mount point ownership/permissions for uid 1000 (required for fresh volumes where the mount point is owned by root) - wait-for-admin — non-admin servers only; waits for dom-admin01a port 1352 to be available on first boot, then requires it to stay open continuously for 2 minutes before proceeding (dom-admin01a restarts itself internally after its own OTS bootstrap, briefly closing the port — a single successful check isn't enough, since a joining server's own registration attempt is one-shot and won't retry). Skipped entirely if notes.ini already exists.

Prerequisites

• Kubernetes cluster with APISIX (routes managed via Admin API — no ingress controller required)
• Custom dom-router Lua plugin installed on that APISIX cluster (per-user mail routing — not installed by this chart, see Default routes)
• A StorageClass that supports ReadWriteOnce volumes
• Image pull access to hclcr.io (secret: regcred)
• (optional) Prometheus Operator with kube-prometheus-stack release label for ServiceMonitor discovery
• (optional) Loki instance reachable from the cluster — required when alloy.enabled: true

Incremental deployment

Two per-server flags control deployment:

• enabled (default true) — controls whether the StatefulSet, Service, and OTS config are created
• register (default true) — controls whether the server is included in admin's autoRegister list (admin pre-creates the server ID during OTS)

The intended rollout order:

1. dom-admin01a — bootstraps the domain from scratch (One-Touch Setup, type admin)
2. dom-admin01b — joins the domain; the hook Job extracts its .id from dom-admin01a's PVC
3. All remaining servers — same pattern

To enable the next server, set enabled: true and run helm upgrade.

Set register: true + enabled: false to have admin pre-register a server without starting it yet — the hook Job extracts its .id immediately, so the pod can start cleanly on the next deploy.

Startup behaviour

First boot (empty PVCs) — timing varies by server type, from a few minutes (admin/files/ldap) up to 15-20+ minutes for mail (larger storage, DAOS/mail-file initialization): 1. Non-admin pods stay Pending until the hook Job creates their server.id Secrets (Job waits for dom-admin01a to complete OTS and become Ready first) 2. wait-for-admin then waits ~2 more minutes to confirm dom-admin01a's port has stabilized past its own internal post-OTS restart (see Architecture) 3. Each non-admin server then runs its own OTS and restarts once internally as part of normal Domino setup

Subsequent boots — wait-for-admin is skipped (detects existing notes.ini), all pods up in ~2 minutes.

One-Touch Setup (OTS)

OTS configuration is stored in the ConfigMap domino-ots-setup with a separate key per server (DominoAutoConfig-<name>.json), mounted as /run/secrets/setup/DominoAutoConfig.json inside each container.

File structure

files/ots/
  first.json.tpl        # template for admin server (type: first)
  additional.json.tpl   # template for all other servers
  parts/                # JSON sections included by the templates above

The .tpl files are rendered as Helm templates. JSON sections in parts/ are included via $files.Get.

How values get into OTS

The final JSON is assembled entirely by Helm at render time: serverTasks, notesINI (merged from otsDefaults / otsTypes.<type> / servers.<name>.otsNotesINI), autoRegister.serverNames, IDVault, DAOSEnable (auto-set when daosStorage is defined on the server), the OIDC IdP Catalog (oidc.clients.*), and initial user registration (otsUsers.*).

Adding a new OTS section

Create a file in files/ots/parts/ and include it in the appropriate .tpl:

{{ tpl ($files.Get "files/ots/parts/daos.json") . | indent 6 | trim }},

If the section needs Helm values (.Values, .Name, .Server, etc.), wrap with tpl:

{{ tpl ($files.Get "files/ots/parts/daos.json") . | indent 6 | trim }},

Inclusion can be made conditional — for example, only for a specific server type:

{{- if eq $server.type "mail" }}, {{ $files.Get "files/ots/parts/daos.json" | indent 6 | trim }} {{- end }}

Server .id extraction (hook Job)

After each install/upgrade Helm runs a post-install,post-upgrade hook Job (domino-extract-ids) that:

1. Waits for dom-admin01a-0 to be Ready
2. For each non-admin server with enabled: true or register: true, waits until <name>.id appears on the dom-admin01a PVC
3. Compares the file content with the existing Kubernetes Secret — creates or updates only if different
4. The Job stays after completion for debugging; it is deleted before the next run (before-hook-creation)

Deploy

Inspect default values

helm registry login hclcr.io --username <username> --password <password>
helm show values oci://hclcr.io/hcl-domino-workspace-communicate/domino/charts/domino --version <version>

Available versions and chart contents are also browsable via the Harbor UI at hclcr.io.

Deployment via Helm

Download chart and create your own custom values file for your env if needed.

helm pull oci://hclcr.io/hcl-domino-workspace-communicate/domino/charts/domino --version <version>

Use your custom values file in installation command or ommit -f option to use default values.

helm upgrade --install domino \
  oci://hclcr.io/hcl-domino-workspace-communicate/domino/charts/domino \
  --version <version> \
  --create-namespace \
  --namespace <namespace> \
  -f <your-values.yml> \
  --timeout 30m

Values

Image

Global Domino settings

OTS (One-Touch Setup)

Storage

Per-server options

Sequential rollout (hook Job)

Restarts StatefulSet pods in controlled batches on upgrade instead of all at once — each server is its own single-replica StatefulSet, so Kubernetes doesn't sequence restarts between them by default. Everything below only has an effect when sequentialRollout.enabled is true.

Servers whose StatefulSet revision didn't change are skipped, so a no-op upgrade restarts nothing. The Job is idempotent — a failed/re-run Job skips already-rolled-out servers.

Admin-specific bootstrap (type: admin)

Identity/password come from global.admin.* / global.certifierPassword. Remaining bootstrap parameters are passed via extraEnv on the admin server entry:

OTS users

OIDC clients (IdP Catalog)

Scheduling

Observability

Keep config secret (keep-config-secret)

HCL Domino REST API (Keep) configuration is rendered into a Kubernetes Secret keep-config-secret from files/keep-config.json.

identitySecret is sensitive; the rest are plain config.

Secrets and extra objects

IMAP proxy

An optional Python asyncio TLS proxy that routes IMAP connections to the correct Domino mail server based on the user's MailServer LDAP attribute.

APISIX Admin API integration

Routes, upstreams, and stream routes are defined in a dedicated file under charts/domino/files/ (default: apisix-routes.yaml). The file is a Go template — it supports {{ .Release.Namespace }}, {{ .Values.domain }}, {{ .Values.apisix.<key> }} for plain values, and {{ index .Values.apisix.routeSecrets "KEY" }} for sensitive values.

The APISIX admin key is set via apisix.adminKey — the chart creates the Secret automatically. Alternatively, create the Secret manually and reference it via apisix.secretName.

Route/upstream bodies map directly to the APISIX Admin API schema — see charts/domino/files/apisix-routes.yaml for the actual structure. routeSecrets holds the sensitive values, everything else is plain config.

routeSecrets reference:

• filesOidcClientSecret — the OIDC client secret from your IdP for the file-server-oidc-client client (files-web).
• filesApiOidcSessionSecret — a random string used to sign the files-api session cookies (e.g. openssl rand -hex 32).
• filesApiOidcClientSecret — the OIDC client secret from your IdP for the file-api-oidc-client client (files-api).

Default routes (apisix-routes.yaml)

mail.<domain>, mobile.<domain> and drapi.<domain> routes require the dom-router plugin (see Prerequisites) for per-user mail server routing.

HTTP routes — all on <domain>, all with HTTP→HTTPS redirect:

dom-router picks a per-node upstream based on the user's mail server.

TCP stream routes (APISIX port defaults below — override via apisix.streamPorts.* if APISIX listens on different ports):

To use different routes, create a new file in charts/domino/files/ and set apisix.configFile.

Useful commands

# Watch dom-admin01a startup
kubectl logs -f dom-admin01a-0 -n <namespace> -c domino

# Check hook Job result (server .id extraction)
kubectl logs -n <namespace> -l job-name=domino-extract-ids

# Check APISIX routes sync Job result
kubectl logs -n <namespace> -l job-name=domino-apisix-routes

# Verify a server.id Secret was created
kubectl get secret domino-secret-dom-admin01b -n <namespace> -o jsonpath='{.data.server\.id}' | base64 -d | xxd | head

# Port-forward dom-admin01a HTTPS for local testing
kubectl port-forward pod/dom-admin01a-0 8443:443 -n <namespace>

# Uninstall (PVCs are retained — delete manually if needed)
helm uninstall domino -n <namespace>

# List release revisions
helm history domino -n <namespace>

# Rollback to the previous revision
helm rollback domino -n <namespace>

# Rollback to a specific revision
helm rollback domino <REVISION> -n <namespace>