Collabora Online on Kubernetes with Helm

The ingress in front of a Collabora Online Helm deployment must send every request for a given document to the same coolwsd pod. The chart requires load balancers to route by the WOPISrc parameter for this reason. When two users edit one document on different pods, their edits are held in separate server-side sessions, so changes do not reach both screens reliably, and copy and paste between them can fail. The chart also turns off horizontal pod autoscaling, because adding or removing pods moves sessions and breaks the same guarantee. Routing by document identity is therefore a correctness requirement, not a tuning option.

The ingress has to read the WOPISrc value from each incoming request, which identifies the document by the URL the WOPI host gave Collabora. That value appears in the editor entry request and in the document paths and WebSocket connections that follow it, so the routing rule has to work on query arguments or encoded path segments depending on the request. The rule then hashes that value and selects a backend consistently. Confirm the exact expression with the documentation of your ingress controller (Nginx, HAProxy or OpenShift Router) and check how the chart's values pass it through, because each controller uses different syntax for hashing on a request attribute.

Routing by client IP or by cookie alone fails in predictable ways. Many users share one address behind a corporate NAT or a reverse proxy, so an IP hash concentrates sessions on a few pods while leaving others idle, and it still sends one user's second document to the pod already holding the first. Cookie affinity pins a browser to a pod, not a document. A second collaborator on the same file, using another browser or machine, can land on a different pod, which breaks co-editing. A document-level key is the only one that matches the unit Collabora actually keeps in memory, so cookie or IP rules can supplement it but should not replace it.

Test the rule against both kinds of traffic before go-live. Open the same document from two browsers on different networks, then check in the ingress logs or controller metrics that every request carrying that WOPISrc value reached one backend, including the WebSocket upgrade. Repeat with a second document to confirm the hash spreads documents across pods. Also check the WOPI requests that the host makes to Collabora and the paths Collabora uses to call back to the host, so no request type bypasses the rule. Record the results, because a rule that works for the first load but drops the WebSocket will look healthy until users report lost edits.

The detailed high availability design, including replica counts, pod placement and capacity planning, is covered in the separate high availability topic. This section only covers the ingress configuration. Ask the team that owns your load balancers to confirm three things before deployment: which request attribute the rule hashes, whether the rule survives controller reloads and failover, and what happens to open sessions when a pod is replaced. Those answers determine whether editing sessions survive routine maintenance, and they should be written into the change record for the cluster.

Verification for a Collabora Online deployment on Kubernetes should prove four things before users are moved onto it: the pods are ready at the replica count you set, a single document is always served by a single pod, the supported file formats open and save, and collaborative features work between users. Start with the Kubernetes side. Confirm that the Deployment reports the replica count you configured, that every pod passes its readiness probe, and that the ingress controller (Nginx, HAProxy or OpenShift Router, whichever you chose) has healthy backends for each pod. Because the official Helm chart README states that horizontal pod autoscaling is disabled, replica changes should be made by hand and tested by hand, not assumed to scale on their own.

The routing test is the one most often skipped. Open the same document from two browser sessions and confirm, by inspecting the pod logs or the ingress access logs, that both requests reach the same pod. The chart README says load balancers must route by the WOPISrc parameter so that all users editing one document reach the same pod. Then open a second document and confirm it may land elsewhere. If requests for one document split across pods, copy and paste and co-editing will fail in ways that look like random user errors, so treat a split as a blocking defect in the ingress configuration, not a tuning issue.

For file formats, build a short test set that covers the formats your users will actually open: docx, xlsx and pptx, plus PDF, and any other formats in your migration scope. For each file, open it in the editor, make a visible change, save, reload the file from the WOPI host and confirm the change persisted. Check that the saved file keeps its format and opens in desktop Microsoft Office or LibreOffice. Include at least one file with custom fonts and one with tracked changes or comments, since those are where round-trip problems usually show up. Copy and paste is tested with two users on the same document in the same session: one user copies a table or paragraph, the other pastes it, and both confirm the result. Record the exact browser versions used.

The failure test is to stop one pod while users are editing, then observe. Scale the Deployment down by one or delete one pod, and confirm what editors see: which sessions drop, whether the editor shows a reconnect message, whether unsaved edits are lost, and how long recovery takes. Then confirm that new sessions are routed to the surviving pods and that the failed pod is replaced at the configured count. Write down the expected behavior for your users before the test, so the result can be judged against it. Separately, check the WOPI host restriction. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers and using the same protocol, preferably HTTPS, for the server URL as for the Nextcloud installation. Confirm that a request from an address outside that list is refused and that the server URL uses HTTPS.

Load testing is separate from functional verification. Run it against the peak concurrency your organization plans for, not an arbitrary number, and include concurrent editing sessions with active changes, not only idle connections. Ask your sizing provider or internal team for the planned peak and the expected mix of document types, then compare observed CPU and memory against the chart's recommended requests and limits for each pod. Plan the test window so that a failed run can be rolled back without affecting production users, and keep the results with the change record.

The first weeks after go-live show whether the deployment will stay predictable, so start with pod health. Watch restart counts, readiness failures and CPU and memory use for each Collabora Online pod, and compare observed usage with the requests and limits in your values file. The official Helm chart README recommends production requests of 4 cores and 6000 MiB of memory per pod, with limits of 8 cores and 8000 MiB, so use those figures as the baseline and confirm they still fit your document mix. Set alerts for memory that stays close to the limit, because an out-of-memory restart interrupts every open editing session on that pod. Track error rates at the ingress layer too (Nginx, HAProxy or OpenShift Router, whichever you deployed), paying close attention to responses on the WOPI routes. Routing faults often appear there before they show up in pod metrics.

Keep everything that defines the deployment in version control. The values file, the chart version and the Collabora Online image tag should live in the same Git repository as your other cluster manifests, and changes should reach the cluster through a reviewed pipeline or GitOps tool. Record the chart version and the server version separately, because they move on different schedules. Store the WOPI host settings alongside them as well: the allow list of Collabora server addresses, the server URL and the group rules for editing and viewing. These are the settings that break when someone changes only one side of the integration. Keep credentials out of the values file and reference them from your secret store, so that a repository review never exposes them.

Plan major moves onto a new yearly release line as their own project, and test them against your real document set, your WOPI host version and your ingress controller before production. Point releases and security advisories on the branch you run should be applied as they arrive, and the release notes will tell you whether a fix touches your configuration. The 25.04 branch shows the pattern: it was first released on June 19, 2025 as 25.04.2.3, it was still receiving point releases, including 25.04.13 on September 21, 2026, and 25.04.7.5 fixed CVE-2026-23623. Confirm with Collabora how signed updates reach you, and note that the Business subscription includes signed security updates while CODE is a rolling build. Your upgrade scope depends on which release line you run, so confirm that before you schedule the work.

Back up the WOPI host's document storage, such as the Nextcloud data directory and its database, because that is where the files of record live. The Collabora Online editing pods should be treated as stateless: if one is lost, the fix is to redeploy it from version control, not to restore a volume. Confirm this against your chart version and your own storage layout. Your backup job should capture the host's database and file storage together, or files and metadata can drift apart after a restore. Test a restore at least once before relying on it, and check that users can reopen a document after the restore without losing their edits, since that is the outcome the backup exists to protect.

Write runbooks for the decisions that the Helm chart makes easy to change. Each runbook should name the owner, the check to run and the rollback step for the routing rules that send all requests for one document to the same pod through the WOPISrc parameter, the replica count per deployment, the ingress class and annotations, and the TLS configuration. Horizontal pod autoscaling is disabled in the chart because scaling breaks collaborative editing, so replica changes are manual operations and should be recorded as such. Before any replica change or ingress edit goes live, test it with several users editing the same document, since that is the case that fails first when routing is wrong. Review the runbooks after each point release and after each yearly upgrade.