How to Set Up Collabora CODE on Kubernetes With Helm

A Collabora Online page can stay blank or report that the office server is unavailable even after the CODE pod is running. A healthy pod is only one part of the setup: the browser and your WOPI application must reach Collabora over the public hostname, TLS and proxy settings must agree, and Collabora must trust the WOPI host. The official Collabora Helm chart deploys the server into Kubernetes; it does not install or configure Nextcloud, ownCloud, or another WOPI host for you.

This guide uses the Collabora-maintained Helm chart with an NGINX Ingress example. Replace the sample domains with your own. CODE is Collabora Online Development Edition, intended for evaluation, home use, and small teams; Collabora says it is not recommended for production environments that need a stable supported release. For production workloads, evaluate the supported Collabora Online offering and its licensing and support terms.

What you need before installing

• A working Kubernetes cluster, kubectl, and Helm 3 with access to the cluster.
• An Ingress controller installed in the cluster. The example below uses ingress-nginx; the Collabora chart also documents HAProxy and supports other routing configurations.
• A DNS name such as office.example.com pointing to the public ingress address, plus a TLS certificate stored as a Kubernetes Secret in the Collabora namespace.
• A WOPI application such as Nextcloud with a URL such as cloud.example.com. Collabora must be able to reach the WOPI application, and the application and users’ browsers must be able to reach Collabora.
• A clear TLS plan. This example terminates HTTPS at the ingress and sends HTTP to the Collabora service inside the cluster.

For a quick home or test deployment, a single CODE pod keeps routing simple. Multiple replicas can improve capacity, but Collabora’s Kubernetes guide calls out a WOPISrc-based load-balancing requirement so editing sessions for the same document reach the same pod. Do not scale replicas before confirming that your ingress controller can provide the needed affinity.

Step 1: Add the official chart and select a version

Collabora publishes its chart from the CollaboraOnline project. The release page currently lists chart version 1.3.5 (checked October 6, 2026). Inspect the versions available in your environment and pin the chart version so a later repository update does not silently change the chart you deploy:

helm repo add collabora https://collaboraonline.github.io/online/
helm repo update
helm search repo collabora/collabora-online --versions

The official chart repository is useful for checking the current defaults before writing overrides:

helm show values collabora/collabora-online --version 1.3.5

If your repository lists a newer compatible chart when you follow this guide, review its release notes and values before substituting that version. The chart version and the CODE application image version are related release inputs, but they are not the same setting.

Step 2: Create a namespace and protect the admin password

Create the namespace and a Kubernetes Secret for the chart’s optional Collabora admin credentials. Replace the placeholder password with a strong secret, or create the Secret through your organization’s secret manager or GitOps secret workflow. Do not commit a real password in values.yaml.

kubectl create namespace collabora

kubectl -n collabora create secret generic collabora-admin \
  --from-literal=username=admin \
  --from-literal=password='REPLACE_WITH_A_LONG_RANDOM_PASSWORD'

The chart supports referencing an existing Secret. Enabling this avoids placing the admin password directly in the Helm values file. Keep the Secret restricted to the namespace and users or service accounts that administer this deployment.

Step 3: Configure the hostname, WOPI host, and ingress

Create a file named collabora-values.yaml. This example assumes ingress-nginx, a TLS Secret named office-example-com-tls, and Nextcloud at https://cloud.example.com. The alias group must name the WOPI application host that Collabora is allowed to contact; it is not the public Collabora hostname.

replicaCount: 1

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: office.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: office-example-com-tls
      hosts:
        - office.example.com

collabora:
  aliasgroups:
    - host: "https://cloud.example.com:443"
  extra_params: "--o:ssl.enable=false --o:ssl.termination=true"
  existingSecret:
    enabled: true
    secretName: collabora-admin

The chart’s documented example uses aliasgroups to allow the WOPI host and these SSL parameters when a reverse proxy terminates TLS. In this arrangement, external traffic to office.example.com uses HTTPS, while the ingress forwards traffic to Collabora over HTTP inside the cluster. If your ingress uses TLS passthrough or a different internal protocol, do not copy these SSL flags blindly; adjust them to match the actual TLS path and the chart’s current values.

Confirm that the TLS Secret exists in the collabora namespace. If you use a different ingress controller, replace the class and annotations with that controller’s documented equivalents. Keep websocket traffic enabled and allow long-lived connections; controller defaults vary.

Step 4: Render and install the chart

Render the manifests first to catch YAML errors and review the generated Ingress, Service, and workload settings. Then install the pinned chart release:

helm template collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

helm upgrade --install collabora-online collabora/collabora-online \
  --namespace collabora \
  --version 1.3.5 \
  --values collabora-values.yaml

Watch the resources as they start:

kubectl get pods,services,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Wait for the pod to become Ready before connecting the WOPI application. If it remains Pending, check whether the cluster has enough schedulable CPU and memory and whether any node selectors, taints, or resource quotas prevent placement. The chart leaves resource requests and limits for the operator to choose; Collabora’s README provides larger example resource values for production-style environments, but actual sizing depends on concurrent editing and document workload.

Step 5: Connect Nextcloud or another WOPI host

Open your WOPI application’s Office or Collabora settings and enter the external service URL, https://office.example.com. In Nextcloud, the administration manual describes setting the URL of the Collabora Online server in the Office administration settings. Also check the Nextcloud WOPI request allow list if your setup restricts which hosts may connect. The address must be reachable both by end-user browsers and by the application server that makes WOPI requests.

If the connection fails with an “unauthorized WOPI host” or similar message, compare the actual WOPI host URL with collabora.aliasgroups. Check the scheme, hostname, and port, and add any legitimate alternate hostnames deliberately. Avoid broad host patterns unless you understand their effect. If you use more than one WOPI application, follow the chart’s documented alias group structure for each host rather than allowing every domain.

When should you scale beyond one pod?

For a small trial, one replica with autoscaling disabled avoids routing complexity. For multiple replicas, the Collabora chart README shows NGINX affinity based on the WOPISrc query argument. Add the documented annotation to the ingress when using ingress-nginx:

nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"

This directs requests for the same document to the same backend pod, which is important for collaborative editing and clipboard requests. Check the documentation for your exact ingress-controller version; an annotation supported by ingress-nginx is not automatically valid for HAProxy, Traefik, or a Gateway API implementation. After enabling more replicas or autoscaling, test simultaneous edits to the same document and watch the Collabora logs and ingress access logs. Resource sizing, session behavior, and high availability need workload-specific validation.

Check the deployment from the outside

1. Confirm Kubernetes reports the pod as Ready and the Service and Ingress exist: kubectl get pods,svc,ingress -n collabora.
2. Check the public discovery endpoint. It should return XML rather than a browser or proxy error:

   curl -fsS https://office.example.com/hosting/discovery | head -c 300

3. Open the WOPI application and edit a test document. Confirm the editor loads, changes save, and reopening the document shows the saved content.
4. If using multiple replicas, open the same document in two sessions and confirm both can collaborate without repeated reconnects. This helps identify missing session affinity.
5. Review logs for TLS, WOPI authorization, or upstream errors:

   kubectl logs -n collabora deploy/collabora-online --tail=100

   If the chart creates a differently named workload, use kubectl get deployments -n collabora and substitute the actual name.

A successful discovery response confirms the public endpoint is serving Collabora metadata; it does not prove that WOPI authentication or document saving works. The end-to-end document test is the final check.

Common failure points

• Ingress returns 404 or 502: verify DNS, ingress class, TLS Secret, and service endpoints. Confirm ingress can reach the Collabora Service on the chart’s service port.
• Discovery works but the editor stays blank: inspect browser console errors and proxy logs. Check HTTPS termination settings, websocket handling, and long request timeouts.
• Unauthorized WOPI host: allow the WOPI application’s origin in aliasgroups; do not substitute the office-server hostname.
• Pod restarts or is evicted: inspect kubectl describe pod and container logs, then set realistic resource requests and limits for the available cluster.
• Editing becomes unstable after adding replicas: verify WOPISrc-based affinity and confirm the controller preserves the query argument when routing requests.

With the chart installed, the discovery endpoint reachable, and a real document successfully opened and saved through the WOPI application, the core CODE deployment is working. Keep the chart version pinned and repeat these checks after chart upgrades, ingress changes, or scaling changes.

Official references

• Collabora-maintained Kubernetes Helm chart and deployment guide
• Collabora Helm chart values
• Collabora chart releases
• Collabora Online Development Edition (CODE) guidance
• Nextcloud Office configuration manual
• ingress-nginx annotations documentation
• Helm install command reference