Why load balancing Collabora Online needs WOPISrc routing
When more than one Collabora Online server sits behind a load balancer, every editor of a given document must land on the same server. Collabora Online keeps the live editing session for a document in the memory of the server that opened it. If a second editor's requests reach a different server, that editor is working on a copy of the document that cannot see the first editor's changes, and features such as co-editing, live cursors and copy and paste between sessions can fail. The control that makes this possible is the WOPISrc query parameter. The WOPI host (Nextcloud or another platform) includes the document's WOPI source URL in each request to the editor, and the load balancer can hash on that value so that one document always maps to one backend.
A plain round-robin or least-connections balancer spreads requests across servers without regard to which document they concern, so two people opening the same file can be split across two servers. Each server then holds its own session for that file, and the editors diverge. The official Collabora Online Helm chart README states that load balancers must route by the WOPISrc parameter so all users editing one document reach the same pod, and it turns off horizontal pod autoscaling for the same reason, because scaling breaks collaborative editing and copy and paste. The same constraint applies to virtual machine and bare-metal deployments, so the balancer configuration is part of the editing design, not an optional tuning step.
You need WOPISrc routing as soon as you run two or more Collabora Online servers for one WOPI host, whether on Kubernetes, on separate VMs or on physical servers. A single server with the built-in CODE app or one dedicated instance does not need it. Confirm with your WOPI host's documentation how it sends the WOPI source, and confirm with Collabora which version of your server and ingress supports the routing setting you plan to use, before you size the cluster or write the balancer rules.
HAProxy or Nginx: which balancer fits your environment
HAProxy is a common choice when a platform team already runs it at the edge and wants stickiness keyed on the document rather than on a client cookie. Collabora's Helm chart README lists HAProxy as a supported ingress, so the routing logic can be expressed in the same tool your operators already monitor. The core idea is to hash the WOPISrc query parameter so that every request for one document maps to one backend.
- Backend stickiness: Use a
url_param WOPISrcbalance rule with a consistent hash type, so the mapping stays stable when servers are added or removed. - Tunnel timeouts: Set client and server tunnel timeouts long enough for WebSocket sessions to stay open during editing, and confirm the values against the Collabora documentation for your version.
- Health checks: Use an HTTP check against the Collabora discovery or health endpoint so a failed server leaves rotation without dropping every session on the others.
- Configuration review: Keep the balance and check directives in version control so changes to the backend list are reviewed like code.
- Operator skills: Confirm that your team can read HAProxy stats and logs during an incident, since routing faults show up there first.
Before go-live, confirm the exact directive names and syntax against the Collabora documentation for your version, and test with two users opening one document on separate sessions.
Nginx suits teams that already terminate TLS and proxy applications with it. Collabora's Helm chart README also lists Nginx as a supported ingress. Nginx can hash on the WOPISrc argument so that requests for one document reach one server, but the configuration depends on how your Nginx build and deployment handle upstream hashing and WebSocket upgrades.
- Upstream hashing: Define an upstream block with a hash keyed on the
WOPISrcargument, and use a consistent option where your version supports it, so server changes move as few documents as possible. - WebSocket upgrade headers: Pass the upgrade and connection headers and raise proxy read and send timeouts so editing sessions are not cut during idle periods.
- Health checks: Open source Nginx relies on passive failure detection through
max_failsandfail_timeoutunless you use a separately licensed or third-party module for active checks, so confirm what your build provides. - TLS and the WOPI host: Keep the protocol consistent with the Nextcloud installation, preferably HTTPS, and restrict WOPI traffic to the Collabora server addresses where the host supports it.
- Reload behavior: Plan reloads so existing connections drain gracefully when you change the upstream list.
Confirm each directive, its availability in your Nginx version, and the settings listed in the Collabora documentation for your release before you rely on them.
Both balancers can meet the same requirement, so the decision usually comes down to what your team already operates and how you will verify routing. The Helm chart README is clear that load balancers must route by the WOPISrc parameter in Kubernetes deployments, and that horizontal pod autoscaling is disabled, so the balancer is part of the editing guarantee rather than an optional layer. Neither tool removes the need to size servers or plan updates.
- Existing ownership: Choose the tool that your edge or ingress team already patches, monitors and documents.
- Health check depth: Compare active health checks against passive failure detection, and decide which failure modes you need to catch quickly.
- Change workflow: Consider how backend lists are changed during rolling restarts and who approves those changes.
- Observability: Check that routing decisions, backend health and session timeouts can be seen in your existing monitoring.
- Supported ingress on Kubernetes: If you run the Helm chart, the OpenShift Router is also listed as supported, which may decide the question for OpenShift estates.
Ask Collabora or your platform vendor to confirm which balancer and version combinations they test before you commit.
Configuration settings and when each fits
This table lists the settings that decide whether every request for one document reaches the same Collabora server, and what each one controls. Read each row as a question to answer for your own environment: what the setting does, and the situation in which you would change it. Values for timeouts, weights and hash methods should be taken from your load balancer documentation and tested, not copied from this page.
| Setting | What it controls | When to change it |
|---|---|---|
| WOPISrc URL parameter | The query parameter the balancer reads to choose a backend, so all requests for one document map to the same Collabora server | Set it once and keep it stable. Change it only if your WOPI host sends the document identifier in a different form, and retest sessions afterwards |
| Hash method | How the balancer turns the parameter value into a backend choice, for example a consistent hash on the URL parameter | Choose a consistent or stable hash so adding or removing a server moves as few open documents as possible. Confirm the exact option name in your balancer version |
| Backend server list and weights | Which Collabora servers receive traffic and how much new work each gets | Add or remove servers during scale out, scale in or maintenance. Lower the weight of a server you plan to drain, and confirm how existing sessions behave when a backend leaves |
| Health check path | The endpoint the balancer polls to decide whether a backend is up and should receive new documents | Point it at the Collabora discovery or health endpoint your version exposes, and confirm it with Collabora documentation before relying on it. A check that passes while the server is overloaded hides capacity problems |
| Client and server timeouts for WebSockets | How long idle or long-lived editing connections stay open before the proxy closes them | Raise them when users see sessions drop during quiet editing. Keep them consistent between the proxy and the Collabora server, and confirm values against the vendor's reverse proxy guidance |
| Upgrade and connection headers | Whether the proxy passes WebSocket upgrade requests through to Collabora | Check them first when editing fails to start or falls back to errors. They are needed on every route that carries editing traffic |
| Nextcloud WOPI allow list | Which source addresses may send WOPI requests to the Nextcloud side, restricted to your Collabora server IPs | Update it when Collabora servers are added, replaced or moved behind a new egress address. Behind a load balancer, confirm which address Nextcloud actually sees |
| Protocol consistency | Whether the Nextcloud and Collabora URLs use the same protocol, preferably HTTPS | Keep it aligned across all hosts. A mismatch between HTTP and HTTPS is a common cause of editing failures after a routing change |
Configure WOPISrc balancing step by step
This sequence turns a set of independent Collabora Online servers into one routed pool in which every request for a given document reaches the same server, with WebSocket timeouts and access restrictions in place.
Inventory backends and their WOPI URLs
List every Collabora Online server you intend to place behind the balancer, with its internal address, port and the public hostname Nextcloud or another WOPI host will use to reach it. Record which servers can reach the Nextcloud instance and which the balancer can reach. Confirm with the team that owns each host that the hostnames resolve correctly from the balancer. The step is done when you have one table with one row per backend and no duplicate addresses or ports.
Align the protocol for the Collabora URL
Set the Collabora server URL in your WOPI host to the same protocol as the Nextcloud installation, preferably HTTPS, as the Nextcloud administration manual recommends. Check the balancer's frontend and the Collabora backends for matching TLS termination points, and note where certificates are installed. The step is done when a plain request to the public Collabora hostname returns a valid certificate and the protocol in your WOPI host configuration matches the protocol Nextcloud uses.
Define the url_param WOPISrc backend
In HAProxy, create a backend with balance url_param WOPISrc so the balancer hashes the WOPISrc query parameter, which carries the document's identity, and sends all requests for that document to the same server. In Nginx, use an equivalent hash on the WOPISrc argument with consistent placement. Set health checks against each Collabora server so unhealthy backends are removed. The step is done when a request carrying a WOPISrc value returns the same backend across repeated calls in the balancer log.
Raise tunnel timeouts for WebSocket traffic
Editing sessions run over WebSockets, so the default idle timeouts on the balancer can close active sessions. Increase the tunnel or client and server timeouts in HAProxy, or the proxy_read_timeout and related settings in Nginx, and make sure the Upgrade and Connection headers pass through unchanged. Confirm the exact values with Collabora's current configuration guidance for your version. The step is done when an editing session stays open through an idle period longer than your previous timeout without a reconnect prompt.
Restrict WOPI requests to known IP addresses
Configure the Collabora servers, or the balancer in front of them, to accept WOPI traffic only from the Nextcloud server addresses and the balancer addresses that should reach them, following the restriction described in the Nextcloud administration manual. Keep the allow list in version control so changes are reviewed. The step is done when a request from an address outside the list is refused and a request from Nextcloud and the balancer succeeds.
Verify two users on one document
Open the same document from two Nextcloud accounts, then check the balancer log or the Collabora server logs to confirm both sessions landed on the same backend. Make a change in one session and confirm it appears in the other, and test copy and paste between them. The step is done when both sessions show the same backend and edits sync in both directions without errors.
Verify two documents on different servers
Open two different documents and confirm the balancer distributes them across more than one backend, using the same log check as before. Stop one backend in a test window and confirm documents hashed to it fail cleanly while the others keep working, then restore it. This confirms both the spread and the failure behavior before real users depend on the pool. The step is done when the two documents are on different backends and the outage test behaves as expected.
What breaks without WOPISrc routing
Without WOPISrc routing, the people editing one document can end up on different Collabora Online servers, and each server then holds its own copy of the document state. A round-robin balancer or one that only uses cookies treats every request as independent, so two co-editors opening the same file may be served by two different backends. Each backend loads its own session, so one editor's keystrokes do not reach the other's screen, and the two users appear to be working on separate documents. The Collabora Online Helm chart README gives this as the reason horizontal pod autoscaling is disabled and replicas are set manually, because adding or removing a pod changes which server receives which document.
The symptoms are often intermittent and easy to misread as network or browser problems. Copy and paste between sessions can fail because the clipboard payload is tied to the server holding the session. A WebSocket connection can drop mid-edit when the balancer moves the client or times out the tunnel, and the browser then reconnects. If that reconnect lands on a server with no state for the document, the editor may show a reload prompt, lose unsaved changes that were never committed back to the WOPI host, or open a stale copy. Reproducing this in a test environment is the most reliable way to confirm it: run at least two Collabora Online servers behind your candidate balancer, open one document from two browsers, and then repeat the test with a configuration that routes by the WOPISrc parameter.
Plan the test as a decision input, not a formality. Record which backend serves each request, check that co-editing, copy and paste, and reconnects after a forced connection drop all behave correctly, and repeat the test after any change to the balancer or to the number of replicas. Confirm with your own Collabora Online version and ingress controller how the balancer's health checks and backend additions interact with active sessions, because a server removed from rotation can still hold documents that are open.
Security controls on the routing layer
A WOPISrc-aware balancer sits between Nextcloud and your Collabora servers, so it is a trust boundary as well as a traffic director. The controls below decide who can reach the editing backends, which users can edit, and whether you can reconstruct events after an incident.
Restrict WOPI requests by source IP
Nextcloud's administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers. At the balancer, allow only the Nextcloud hosts to reach the WOPI paths, and confirm that the source addresses the balancer sees match what it expects, especially when a proxy sits in front of it. Check this after every change to the network path, because a wrong address either blocks editing or leaves the backends open.
Use HTTPS end to end
Nextcloud's manual recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS. Terminate TLS at the balancer with certificates that Nextcloud trusts, and decide whether traffic from the balancer to the backends is also encrypted. Verify that WebSocket upgrades succeed over the secure scheme, since a mixed-protocol setup often breaks editing silently.
Patch balancer and backends together
Collabora publishes security advisories for Collabora Online. The 25.04 release notes record that 25.04.7.5, released January 29, 2026, fixed CVE-2026-23623 and updated package signing keys for RPM and DEB users. Treat the balancer, the TLS terminator and every Collabora backend as one patch scope, and confirm with your vendor or package source which release line you run before rolling changes out.
Limit which groups can edit
Nextcloud Office lets administrators restrict which groups can use the editor and which groups can edit rather than only view. The balancer cannot enforce this, so set it on the Nextcloud side and review it as part of the same change. Route only traffic from permitted users, and test with a view-only account and an editing account to confirm both behave as intended.
Keep health checks off the public path
Health check endpoints on Collabora backends reveal which servers are up and how loaded they are. Expose them only on the internal network or to the balancer's own address, and do not publish them through the public hostname that Nextcloud uses. Confirm that the health check path you configure does not pass through the same rules that allow WOPI traffic.
Log balancer access for investigations
Record the WOPISrc value, client address, status code and backend chosen for each request, with the document identifier kept consistent across Nextcloud and Collabora logs. These entries let you trace which user opened a file on which server during an incident. Decide the retention period with your security and privacy teams, and confirm that log fields containing document identifiers meet your data protection rules.
Questions teams ask before configuring WOPISrc routing
Does a small team need WOPISrc routing at all?
Not always. If you run a single Collabora Online server, there is nothing to route between, and WOPISrc routing matters only once requests for one document can land on more than one backend. The official Helm chart README is direct about the reason: horizontal pod autoscaling is disabled because scaling breaks collaborative editing and copy and paste, and load balancers must route by the WOPISrc parameter so all users editing one document reach the same pod. Once you add a second server or replica, the routing rule is no longer optional. Teams that start with one server should still design the proxy layer so that adding a backend later does not change how documents are routed. Confirm your expected backend count with your own sizing before deciding.
What drives the effort of configuring WOPISrc routing?
Four factors shape the work most. The first is the number of backends, because each one needs a health check, a stable address and a place in the routing rule. The second is existing skill with HAProxy or Nginx, since a team that already runs one of them can adapt a config quickly while a team new to both will spend time on WebSocket timeouts and header handling. The third is the target: a Helm deployment on Kubernetes uses the chart's supported ingress options, while a set of virtual machines needs a proxy configuration you write and maintain. The fourth is Nextcloud allow list work. 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, so the proxy and the Nextcloud settings must change together.
Can our own team configure WOPISrc routing without a partner?
Often yes, if the team already operates HAProxy or Nginx and can test WebSocket sessions end to end. The work is well bounded: a balancing rule keyed on the WOPISrc parameter, tunnel timeouts that keep long editing sessions open, health checks, and matching settings in Nextcloud. The risk is in testing. A rule that works for one document can still split sessions for a different WOPI host or fail when a server restarts, and those faults appear only under concurrent editing. Ask yourself whether someone on the team can reproduce multi-user editing on a test stack, read proxy logs for a single document ID, and own the config after handover. If not, a fixed-scope engagement can cover the build and knowledge transfer.
How long does testing take, and what does it depend on?
Testing length depends on the number of backends, the number of WOPI hosts in use, and how many document types and editing patterns you need to verify. A minimal test covers the same document opened by several users, a server restart during an open session, and a long idle period to confirm tunnel timeouts hold. Each added host or backend adds scenarios. Collabora's own documentation does not give a fixed duration for this, so ask any partner for a test plan with named scenarios and a written end condition before you agree a timeline. Timelines in a fixed-scope agreement are set in writing before work starts.
What do you need to provide for routing work?
Plan for access and time from several people. You need administrative access to the proxies (HAProxy or Nginx), DNS control for the Collabora and Nextcloud hostnames, and read access to the Nextcloud configuration so the WOPI allow list can match the Collabora server addresses. You also need a test environment that mirrors production, a set of test documents in the formats your users open, and named change windows for proxy reloads. Ask whether the proxies can be reloaded without dropping existing sessions, since that determines how you schedule cutover. Confirm these items with your own platform owners before the work starts so that the scope reflects what your environment actually allows.
How is the cost of a fixed-scope engagement set?
DeployOpen does not publish a price list. Most engagements are fixed-scope, so the quote follows from a written scope that names the deliverables, the backends and proxies in scope, the Nextcloud changes, the test scenarios, the timeline and the handover. One-time costs cover design, build, testing and knowledge transfer. Recurring costs, if you want them, come from ongoing support, upgrades or continuous testing, which DeployOpen offers as retainers. Costs rise with more backends, more WOPI hosts, stricter change control and more test scenarios. When you ask for a quote, request the scope items, the exclusions, what you must provide, and how changes after sign-off are priced.
What breaks if we skip WOPISrc routing and use plain round robin?
Documents split across servers. Users who open the same file can land on different Collabora backends, each holding its own editing session state, so changes do not converge and copy and paste between users can fail. Collabora's Helm chart guidance treats this as the reason to route by WOPISrc, so every user editing one document reaches the same pod. Tunnel timeouts matter too: WebSocket sessions that the proxy closes during idle periods show up as dropped connections and reconnect loops. Check your proxy logs for one document ID across several users to confirm routing is working before you go live.
How DeployOpen scopes and delivers WOPISrc routing
DeployOpen scopes WOPISrc routing as a written design before any configuration changes. The scope names the balancer in use (HAProxy or Nginx), the ingress or edge layer in front of it, the number of Collabora Online servers and how they are placed (VMs, bare metal or Kubernetes pods), the WOPI hosts that will call them, and the health check, timeout and TLS decisions. It also records who owns each layer, because routing failures often sit between the proxy team and the application team. The deliverables and acceptance tests are agreed in the same document, so the client knows what will be proven and how before the work begins. Most engagements are fixed-scope, and the quote follows from that written scope.
In the client's own infrastructure, the build starts with a lab or staging path that mirrors production routing. DeployOpen configures the url_param balancing rule on the WOPISrc parameter, sets the WebSocket tunnel timeouts, and then tests the behavior that matters: two users opening the same document land on the same server, separate documents spread across the pool, a server removed from rotation drains without breaking open sessions where that is possible, and the WOPI host's allow list and HTTPS settings still match the Collabora server URL. Tests are run against the client's real WOPI host where access allows, and every result is written down with the configuration version it applies to. Items that depend on the client's network, certificates or vendor settings are listed as confirmations rather than assumed.
Handover includes the configuration files, a short runbook for adding or removing a server, steps for checking routing during an incident, and notes on what to re-test after a Collabora Online upgrade or a change to the WOPI host. Ongoing work can be covered by a retainer for upgrades, configuration review and continuing support, scoped in writing like the original build. Each retainer should state which upgrades and which environments it covers, how requests are triaged, and what the client will receive after each change. DeployOpen prepares the systems, documentation and evidence for the client's own reviews, but it does not issue audit reports or certifications.
