How to Set Up a Collabora Online Cluster with Multiple Nodes

A Collabora Online cluster is not just several healthy coolwsd servers behind a round-robin load balancer. Collaborative editing depends on sending requests for the same document to the same Collabora node. Collabora’s Kubernetes chart documents routing by the WOPI document identifier, WOPISrc, for this reason. This guide uses the maintained Collabora Helm chart on Kubernetes as a concrete multi-node setup and notes what must change for a different ingress controller or a non-Kubernetes deployment.

Verified: Collabora’s chart supports multiple replicas and describes per-document affinity using WOPISrc. Deployment-dependent: ingress annotations, TLS termination, resource requests, and whether a session controller is appropriate. Not safe to assume: that any load balancer or every “sticky session” setting will preserve document affinity. Confirm the controller-specific behavior and test it before moving users onto the cluster.

What the cluster does—and what it does not do

In a standard multi-replica deployment, each Collabora node can serve documents, while a proxy sends each document’s requests to one node. This spreads separate documents across the pool. It does not mean every node shares the same live editing process or that a running document can always move seamlessly if its node stops.

Collabora also documents a COOL Controller for Kubernetes that adds a different session-management approach. Its routing and configuration differ from a standalone replica pool. This article configures the simpler WOPI-source affinity model; do not combine it with controller-specific route-token settings unless you have deployed and configured the Controller for your release.

Action: decide whether you need a basic replicated Collabora service for capacity and node redundancy, or a controller-managed setup with session-aware behavior. The latter has additional components and version-specific configuration. Review the Collabora Online Controller overview if you are evaluating that path.

Before you deploy

• A working Kubernetes cluster, Helm, DNS for a public Collabora hostname, and a TLS-capable ingress or reverse proxy.
• A WOPI integration such as Nextcloud, configured to use the single public Collabora hostname rather than individual pod addresses.
• The WOPI host or hosts that Collabora is allowed to accept, entered in the chart’s collabora.aliasgroups configuration.
• Enough CPU and memory for the document workload, plus a way to inspect pod health, ingress logs, and resource use.
• A maintenance window for the initial rollout and a test document with two separate user accounts.

A dedicated Collabora Online service is different from Nextcloud’s built-in CODE server. Nextcloud describes its built-in option as aimed at personal use or small teams and without the advanced scalability features of a dedicated server. Action: if you need a multi-node Collabora pool, plan for the dedicated service and confirm the licensing and support model suitable for your deployment. See the Nextcloud Office installation guide.

Step 1: Choose the routing model

The documented standalone model hashes on WOPISrc, which identifies the document in WOPI requests. Requests for one document must reach the same pod; requests for different documents can be distributed across pods. A generic round-robin rule does not meet that requirement.

Action: use an ingress implementation supported by the chart documentation, such as the documented NGINX or HAProxy ingress examples, or use the chart’s in-namespace reverse proxy where the cluster does not allow a suitable ingress controller. If you use another proxy, verify that it can consistently route requests by the WOPI source for both ordinary HTTP requests and long-lived WebSocket connections.

Step 2: Inspect the chart and select a version

The chart and its values change over time. Before installing, inspect the current official chart README and values rather than copying a configuration written for an older release. The examples below follow the maintained Collabora chart documentation reviewed October 6, 2026; treat the repository’s current release notes and values as authoritative for your installation day.

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

Action: choose a chart version that matches your change-control policy and record the Collabora image version it deploys. Pin the chart version for repeatable upgrades; avoid relying on an unreviewed floating version in production. The chart’s own setup guide is the Collabora Online for Kubernetes README.

Step 3: Prepare values for three replicas

This example assumes the NGINX Ingress Controller, TLS termination at the ingress, and an external WOPI host at cloud.example.com. Replace both hostnames with your own. If TLS terminates elsewhere or you use HAProxy, use that controller’s corresponding, documented configuration instead.

replicaCount: 3

autoscaling:
  enabled: false

ingress:
  enabled: true
  className: nginx
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$arg_WOPISrc"
    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

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

The hash annotation and timeout values above are shown in the chart’s NGINX example. The extra_params line is appropriate only when the reverse proxy terminates TLS and connects to Collabora over HTTP. Do not apply it unchanged if your TLS topology differs. Configure the ingress TLS secret and host according to your certificate manager and local chart values; the excerpt leaves those provider-specific settings out.

Action: save this as my_values.yaml, add the TLS configuration required by your ingress, and compare every key with the selected chart release’s values.yaml. Keep the Collabora public hostname consistent across DNS, TLS, the integration’s Collabora URL, and proxy routing.

Step 4: Install the Collabora release

Install into a dedicated namespace. Replace <chart-version> with the version selected in Step 2; angle brackets here are explanatory placeholders and should not be typed literally.

helm install --create-namespace   --namespace collabora   collabora-online collabora/collabora-online   --version <chart-version>   -f my_values.yaml

For an existing release, use a planned Helm upgrade after checking the release’s migration notes and rendered changes. Avoid deploying a major image or chart update at the same time as your first scaling change; changing one variable at a time makes faults easier to isolate.

Action: inspect the release and wait for all replicas to become ready:

helm status collabora-online -n collabora
kubectl get pods,svc,ingress -n collabora
kubectl get events -n collabora --sort-by=.lastTimestamp

Three desired replicas are not proof that three healthy nodes are serving traffic. Check readiness, recent restarts, scheduling, and ingress endpoints. If pods remain pending, inspect available cluster capacity and the resource requests and limits in the chart values.

Step 5: Connect the WOPI application

In the file platform’s office integration settings, set the Collabora server URL to the public endpoint, for example https://office.example.com. Do not point the application at a pod IP or a Kubernetes-only service name unless the integration itself runs inside the cluster and that private routing is explicitly supported by your design.

The hostname in aliasgroups must identify the WOPI host that stores and serves documents; it is not the Collabora hostname. A mismatch can cause WOPI host validation failures even when the Collabora pods and ingress are healthy.

Action: enter the same public Collabora URL in the integration’s configuration, save it, and verify that its connectivity or discovery check succeeds. If it fails, check the application’s WOPI allowlist, Collabora’s alias groups, DNS, TLS, and proxy headers before changing replica count.

Step 6: Test document affinity and collaboration

Open a test document and inspect ingress or proxy logs to confirm which backend serves it. Then open that same document from a second user session and verify that both users can edit and see each other’s changes. Open a different document and confirm that the load balancer can send it to another healthy pod. The test is about routing and collaboration, not just whether the landing page returns HTTP 200.

Action: verify that the WOPI-source hash is present and applied consistently to the requests generated for the same document, including the WebSocket upgrade. If users do not see one another’s edits, compare backend selection for the same document before investigating the WOPI host or browser cache.

Step 7: Test health handling and node loss

Readiness checks should keep an unhealthy or starting pod out of service. The chart includes startup, readiness, and liveness probe settings, but exact behavior and timing depend on the selected chart version and cluster. A pod becoming unavailable can interrupt documents currently running on that pod; a basic affinity pool should not be described as live session replication.

Action: in a test environment, remove one pod from service during an active editing session, observe client behavior and proxy routing, then reopen the document and confirm it reaches a healthy pod. Do not perform this test on active production documents without an approved maintenance plan. For stricter session continuity, evaluate the COOL Controller and its version-specific route-token setup.

Step 8: Monitor, tune, and upgrade deliberately

Track pod restarts, CPU and memory usage, request and WebSocket errors, ingress latency, and user reports about document loading or reconnecting. Collabora’s chart documentation includes Kubernetes monitoring guidance. Set resources from observed workload rather than copying example numbers: document size, concurrent sessions, fonts, and editing patterns all affect capacity.

Collabora recommends running the same version on all load-balanced nodes so clients receive consistent, version-specific web assets. During upgrades, use the chart’s supported rollout strategy, watch readiness and logs, and test an open document from multiple users before declaring the change complete.

Action: keep the chart version, image version, values file, and test results together in your change record. Schedule upgrades, confirm all replicas converge on the intended version, and retain a rollback plan compatible with the chart’s supported rollback behavior.

Common misconceptions to check

• “Three replicas automatically create a working cluster.” Replicas alone do not configure document affinity. Confirm that the ingress hashes on the WOPI source or that your controller provides the intended session routing.
• “Sticky sessions based on a user’s IP are enough.” That is not the rule described by Collabora’s chart for its standalone Kubernetes pool. Users collaborating on one document must converge on the same node even when they arrive from different devices or networks. Configure document-based affinity and test with two users.
• “A healthy homepage proves the cluster is ready.” It proves only that one HTTP request returned successfully. Test opening and collaboratively editing a document, WebSocket upgrades, and behavior when a pod becomes unavailable.
• “Adding a node guarantees active sessions survive node loss.” A basic WOPI-source-affinity pool routes a document to a node; it does not establish that its in-memory editing process is replicated. Confirm expected recovery behavior in a controlled test or assess the separate session-management features of the Controller.

For non-Kubernetes installations, the architecture principle is the same, but Kubernetes chart commands and ingress annotations do not apply. Use the proxy configuration for your Collabora version and load balancer, ensure long-lived WebSocket connections are supported, and implement per-document routing using the WOPI source. The Collabora Online SDK manual describes load balancing and the WOPISrc affinity requirement; verify the equivalent section in the manual for the release you operate.