Why Collabora Online needs a reverse proxy configured for WebSockets and WOPISrc routing
If your team runs Nextcloud or another WOPI host and wants browser editing behind your own proxy, the proxy has to do more than pass HTTP traffic to coolwsd. It must forward the Collabora Online paths and the WebSocket connections that carry live editing sessions, terminate TLS correctly, and keep long-lived sessions open with timeouts set for editing rather than for short web requests. A proxy that handles ordinary web pages but drops or times out WebSocket traffic will load the editor and then fail during editing, which is the failure most teams see first.
You need this page when Collabora Online will sit behind Nginx, Apache or HAProxy, when the WOPI host and the Collabora server use separate hostnames, or when you run more than one Collabora Online server. The official Collabora Online Helm chart README makes the multi-server case explicit: horizontal pod autoscaling is disabled because scaling breaks collaborative editing and copy and paste, replicas are set manually, and load balancers must route by the WOPISrc parameter so that everyone editing one document reaches the same pod. The same principle applies to a non-Kubernetes pool, so the routing decision belongs in the design before you choose a proxy product.
Before you change any configuration, confirm three things with your own environment: the hostname and scheme your WOPI host will use to reach Collabora Online, which proxy product and version your platform team supports, and whether you will run one server or a pool. The Nextcloud Office configuration guide recommends using the same protocol for the Collabora server URL as for the Nextcloud installation, preferably HTTPS, and restricting WOPI requests to known Collabora server addresses. Those choices shape the proxy rules that follow.
Choosing Nginx, Apache or HAProxy for Collabora Online
Nginx is the proxy most often named in Collabora's own deployment material. The official Helm chart README lists Nginx as a supported ingress option for Collabora Online, which makes it the lowest-risk starting point when you want a configuration that matches the vendor's tested path. It handles TLS termination, path-based routing to coolwsd, and WebSocket upgrades with a short, well-documented set of directives.
- Vendor alignment: The Helm chart README names Nginx among the supported ingress controllers, so examples and troubleshooting references are easiest to find for this proxy.
- WebSocket upgrades: You must pass the
UpgradeandConnectionheaders through to coolwsd for editing sessions to stay open. - Long sessions: Raise
proxy_read_timeoutandproxy_send_timeoutabove the defaults so idle editing sessions are not dropped. - Load balancing: Open-source Nginx offers hash-based upstream selection, which you can key on the WOPISrc parameter when you run more than one server.
- Team fit: Teams that already run Nginx for web applications can reuse their certificate handling and logging.
Before you commit, confirm the exact directives and header rules against Collabora's current documentation for your release, because proxy guidance changes between branches.
HAProxy is the proxy to weigh when load balancing is the main requirement. The Helm chart README lists HAProxy as a supported ingress, and its routing rules are well suited to keeping every user editing one document on the same backend. That routing requirement comes from the chart's own guidance: load balancers must route by the WOPISrc parameter so all users editing one document reach the same pod.
- Document affinity: Build a stick table or hash rule on the WOPISrc parameter so that all sessions for one document land on one coolwsd instance.
- Health checks: Configure active health checks against the coolwsd endpoint so failed backends are removed from rotation.
- Operational visibility: The built-in statistics page and logs make it easier to see which backend holds a session.
- Team fit: Teams that run HAProxy for database or API traffic often prefer it for this role because the configuration model is familiar.
- Scaling limits: Adding backends is only safe if your routing keeps documents pinned. Test that a document opened by two users reaches the same backend before you add capacity.
Confirm the routing key and header handling with your Collabora release notes, and test failover with real editing sessions, not only health check responses.
Apache HTTP Server is common in estates that already run it for PHP or legacy web applications, and it can sit in front of coolwsd. Collabora's material for this proxy is less prominent than for Nginx and HAProxy, and the Helm chart README does not list Apache among its supported ingress options. Treat Apache as a supported-in-principle choice that needs confirmation before you build on it.
- Documentation gap: Confirm the required proxy modules, WebSocket handling and path rules against Collabora's current documentation for your release.
- Module dependencies: WebSocket forwarding and proxy load balancing depend on specific Apache modules being enabled, so check that they are available in your distribution build.
- Existing estate: If Apache already terminates TLS for your Nextcloud host, adding a separate proxy for Collabora may add a moving part you do not need.
- Load balancing: Confirm how sticky routing on the WOPISrc parameter can be configured, because document affinity is the requirement that matters most.
- Support path: Ask Collabora or your implementation partner which Apache configuration they have tested before you rely on it in production.
If the documentation does not cover your exact layout, choose Nginx or HAProxy for the Collabora tier, even if Apache serves the rest of your estate.
The right proxy usually depends less on features than on who will operate it at 2 a.m. A proxy your team already patches, monitors and can troubleshoot is safer than a better-suited tool that only one engineer understands. Map the decision against three questions: which proxy your platform team runs today, whether you need sticky routing across several coolwsd servers now or later, and how much of the configuration you can test in a staging environment before production.
- Existing standard: Choose the proxy already in your ingress or edge layer unless it cannot meet the WOPISrc routing need.
- Single server: A single coolwsd instance has no document affinity problem, so any of the three can work if its WebSocket handling is correct.
- Multiple servers: Plan for WOPISrc-based routing from the start, because changing the routing key later disrupts open sessions.
- Kubernetes: If you deploy with the Helm chart, the supported ingress options are the clearest path.
- Staging: Test long editing sessions, reconnects and certificate renewal in a copy of your production layout.
Whatever you select, write down the proxy version, the routing key and the timeout values so the choice can be reviewed during upgrades.
How to configure the proxy step by step
This sequence takes a reverse proxy from a bare server to a working Collabora Online front end, with the hostname, certificates, routes, WOPI restrictions and timeouts each confirmed before the next step begins. Each step ends with a check you can run yourself.
Set the subdomain and DNS record
Choose a dedicated hostname for the Collabora Online server, such as office.example.com, and create a DNS record that points it at the proxy's public address. Your network team or DNS administrator makes the record, and you confirm it from a machine outside your internal network. The step is complete when the name resolves to the expected address from both inside and outside your network, and the proxy host is reachable on ports 80 and 443. Keep the hostname identical in the Nextcloud server URL later, so the browser and the WOPI host agree on the origin.
Obtain and install the TLS certificate
Request a certificate for the chosen hostname from your internal certificate authority or a public one, then install the certificate and private key on the proxy. Your security or platform team owns this step, since key handling and certificate lifetime rules come from your own policy. Confirm the chain is complete and the certificate names match the hostname with a command such as
openssl s_clientagainst port 443. The step is done when the handshake completes without warnings from a client that trusts your certificate authority.Forward the coolwsd routes and WebSocket upgrade
Configure the proxy to forward the Collabora Online paths to coolwsd, including the discovery endpoint, the editor and document paths, and the WebSocket route used for live editing. Set the upgrade headers on the WebSocket location so the connection switches protocols instead of closing. Use the path list from the Collabora Online documentation for your installed version, and confirm each path against your release. The step is complete when the discovery URL returns the expected XML from outside your network and a test document opens in the editor.
Restrict WOPI requests to Collabora server addresses
Limit which clients can reach the WOPI endpoints by allowing only the IP addresses of your Nextcloud servers or other WOPI hosts, as the Nextcloud administration manual recommends. Your network or platform team applies the rule at the proxy or firewall and keeps the list in version control. Test from an address on the allow list and from one outside it, and record the result. The step is complete when the allowed host can open documents and the disallowed address receives a denial.
Match the HTTPS protocol across the server URLs
Set the Collabora Online server URL in the WOPI host to use the same protocol as the Nextcloud installation, preferably HTTPS, as the Nextcloud manual advises. Check that the public URL that coolwsd advertises matches the hostname and scheme the proxy presents, so the editor does not load mixed content or fail its origin checks. Your Nextcloud administrator makes the change in the Office settings. The step is done when the Nextcloud Office settings save without error and the editor opens over HTTPS in the browser console without mixed-content warnings.
Set timeouts for long editing sessions
Raise the proxy's read and send timeouts for the WebSocket and document routes so that idle editing sessions are not cut off mid-edit. The right values depend on your users' session habits and your proxy's defaults, so confirm them with your operations team rather than copying a single number from a guide. Apply the same settings on any load balancer in front of the proxy. The step is complete when a document left open and idle beyond your previous timeout still accepts edits when the user returns.
Verify the WebSocket holds under load
Open a test document, leave the session connected, and watch the WebSocket connection in the browser developer tools while two users edit the same file. Confirm the connection stays in the open state, that edits sync between the two sessions, and that copy and paste works. Repeat the test after any change to the proxy configuration or the Collabora Online version. The step is complete when the connection holds through the full test window and both sessions show the same content.
Which subdomain layout and proxy settings fit each deployment
This table compares the subdomain layout, TLS placement, pod routing and timeout choices for a Collabora Online proxy setup, with the condition under which each option fits. Read each row against your user count, replica count and whether your identity and network teams require encryption between the proxy and coolwsd. The main takeaway is that multi-pod deployments need WOPISrc-aware routing, and long sessions need timeouts agreed with your host application before go-live.
| Decision | Option | When it fits | What to confirm |
|---|---|---|---|
| Subdomain layout | Single subdomain with path routing | Small single-node deployments where one hostname can serve both the WOPI host and the Collabora paths | Which paths your build of coolwsd serves and that the WOPI host URL matches the proxy hostname exactly |
| Subdomain layout | Dedicated collabora subdomain | Most production setups, since it keeps Collabora routes separate from the host application and simplifies certificates and allow lists | DNS record, certificate coverage for the subdomain, and the WOPI allow list entries your host expects |
| TLS placement | SSL terminated at the proxy | Environments where the proxy holds the certificate and the internal network is already trusted | Whether coolwsd is configured to accept forwarded HTTPS and that the proxy sends the original scheme and host headers |
| TLS placement | End to end encryption to coolwsd | Regulated environments or networks where traffic between the proxy and the Collabora server must also be encrypted | Internal certificate handling, trust store on the proxy, and the performance impact measured in your environment |
| Pod or server count | Single node behind a simple upstream | One coolwsd server with a stable upstream address and no need to keep editing sessions on a specific backend | Connection limits on the proxy and that long-lived WebSocket connections are allowed through |
| Pod or server count | Multiple pods with WOPISrc-based routing | Several replicas, where all users editing one document must reach the same pod | That the load balancer hashes on the WOPISrc parameter, that sticky routing survives failover, and the replica count set manually |
| Session timeouts | Extended read and send timeouts for WebSocket routes | Long editing sessions and large documents, where default proxy timeouts would close active connections | Timeout values agreed with your host application and tested against real session lengths in a staging environment |
| Session timeouts | Default proxy timeouts | Short, occasional editing with no WebSocket traffic expected through the proxy | Whether editing sessions drop during idle periods, which usually signals timeouts set too low |
Setting timeouts so long editing sessions do not drop
Default proxy timeouts close idle WebSocket connections, and a Collabora editing session depends on keeping that connection open. A user who reads a document without typing still holds a live WebSocket to coolwsd, and a long review can pass through quiet stretches. Nginx, Apache and HAProxy each apply their own idle limits to proxied connections, and these limits are usually set far below the length of a working session. When the proxy cuts the connection, the editor may show a disconnect or lose unsaved changes, and the failure often looks like a Collabora bug when it is a routing setting.
In Nginx, the settings to review are proxy_read_timeout and proxy_send_timeout on the location that forwards WebSocket traffic, along with the Upgrade and Connection headers that the upgrade depends on. Apache needs the proxy module and WebSocket upgrade handling configured on the same path, and its Timeout and ProxyTimeout directives govern how long an idle backend connection survives. HAProxy uses timeout tunnel for upgraded connections, and this value matters more than timeout client and timeout server once the connection has switched protocols. Check each value against the coolwsd documentation for your release and the Nextcloud or WOPI host guidance, and do not copy numbers from a forum post into production without testing them.
Test with a session longer than your current limit. Open a document through the proxy, leave it idle for longer than the proxy's read timeout, then type and save, and repeat with a second user co-editing the same file. Watch the proxy error log and coolwsd logs for closed connections at the moment of disconnect. Ask your team to record the timeout values they chose, the coolwsd version tested and the length of the longest session that stayed stable, so that any change to the proxy, the Collabora release or the load balancer can be checked against the same test.
Security controls at the proxy layer
The reverse proxy is the only component facing clients and WOPI hosts, so it carries most of the exposure. The controls below decide who can reach coolwsd, which internal paths stay closed, and whether the proxy keeps pace with Collabora's security advisories.
TLS termination and certificates
Terminate HTTPS at the proxy with certificates your organization issues and renews. The Nextcloud administration manual recommends using the same protocol, preferably HTTPS, for the Collabora server URL as for the Nextcloud installation, so the browser, the WOPI host and the proxy should all agree on the scheme. Confirm how certificates are renewed, which TLS versions and ciphers the proxy offers, and whether the WebSocket upgrade path uses the same certificate chain as the document paths.
Restricting WOPI access by host IP
The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers. Apply that allow list at the proxy as well as in coolwsd, so requests to the WOPI endpoints from unknown addresses are rejected before they reach the application. Keep the list current when the WOPI host changes addresses, and test that a request from an address outside the list is refused.
Keeping admin endpoints private
coolwsd exposes administrative and diagnostic paths that should never be reachable from the public internet. Configure the proxy to return a denial for those paths on every public hostname, and allow them only from a management network or a bastion host. Review the route list after each upgrade, because a new path added in a release can be forwarded by a catch-all rule that was written earlier.
Forwarded client address headers
coolwsd logs and makes access decisions based on the address it sees, so the proxy must set forwarding headers consistently. Set the forwarded-for and forwarded-proto headers at the proxy, and make sure the proxy overwrites any values a client sends instead of passing them through. Check that the Collabora configuration trusts only the proxy's address for these headers, or client-supplied addresses could bypass the allow list.
Patching the proxy with Collabora advisories
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 that package signing keys were updated for RPM and DEB users. Patch coolwsd to the fixed point release and refresh repository signing keys, then patch the proxy package on the same schedule. Ask your proxy vendor or distribution for its own advisory feed so both layers are tracked together.
Questions teams ask before configuring a Collabora Online reverse proxy
How much does a Collabora Online reverse proxy configuration cost?
DeployOpen does not publish a price list, and a quote follows from a written scope, so the cost depends on what that scope covers. The main drivers are the number of hostnames and paths to route, whether SSL terminates at the proxy or further upstream, how many existing proxies or load balancers must change, and how much testing with real documents is needed before sign-off. Ask for a quote that lists each proxy, each hostname, the test cases and the handover documentation. If you are sizing the software itself, the Business plan from Collabora costs 3 euros per user per month for up to 99 users, according to the pricing page, and that subscription is separate from the proxy work.
Can our team configure the reverse proxy without outside help?
Yes, if your team already runs Nginx, Apache or HAProxy in production and can read the WOPI and WebSocket requirements in the Collabora documentation. The work is mostly configuration, but it needs someone who can test editing sessions end to end, not only check that the login page loads. Teams that run their own proxy usually handle the basic routes and hand off the harder parts, such as long session timeouts, multiple upstream servers or unusual network paths. A partner is most useful when the proxy is shared with other applications and changes carry a wider blast radius.
What do we need to provide before the work starts?
Plan to provide the following before the engagement begins:
- DNS control for the hostname that will serve Collabora Online, and for any subdomain layout you choose
- A TLS certificate or access to your certificate authority, plus the chain your clients trust
- Network access from the proxy to the coolwsd servers and from your Nextcloud or other WOPI host to the proxy
- A set of test documents in the formats your users edit, such as docx, xlsx and pptx, with known-good expectations
- Named contacts for the WOPI host, the network team and the people who approve production changes
Confirm these with your own environment early, since access approvals often take longer than the configuration itself.
How long does a reverse proxy configuration take?
The duration depends mainly on environment complexity rather than on the product. A single proxy with one hostname, SSL terminated at that proxy and a single coolwsd server is the simplest case. Time grows with each additional hostname, each proxy layer, each upstream server, and each approval step for DNS or certificates. Testing also takes time, especially when you need to confirm that long editing sessions survive your chosen timeouts. Ask for a timeline in the written scope that separates environment access, configuration, testing and handover, and confirm which steps depend on your change windows.
When does a multi-pod deployment change the proxy routing requirements?
Routing changes as soon as more than one Collabora Online pod or server handles editing. Requests must reach the same pod for every user editing a given document, so the load balancer needs to route by the WOPISrc parameter rather than by round-robin alone. The official Helm chart README states that horizontal pod autoscaling is disabled because scaling breaks collaborative editing and copy and paste, so replica counts are set manually. It also lists Nginx, HAProxy and OpenShift Router as supported ingress options. If you plan to run several pods, confirm the routing design before building the first proxy, because retrofitting it later touches every hostname and upstream definition.
Which WOPI and security settings should the proxy enforce?
The proxy should forward the WOPI and WebSocket routes that Collabora Online needs and nothing else. The Nextcloud administration manual recommends restricting WOPI requests to the IP addresses of the Collabora servers and using the same protocol for the Collabora URL as for Nextcloud, preferably HTTPS. Those settings need to match at the proxy, in the Nextcloud configuration and in coolwsd. Confirm the exact allow-list and certificate handling in your environment before go-live, and check that a request from an unlisted address is refused.
What should we test before we accept the proxy configuration?
Test the full editing path, not only the login page. Open documents of each format your users rely on, edit them from two browsers, confirm that changes sync, copy and paste works, and keep a session open long enough to hit your timeouts. Repeat the checks after a restart of the proxy and after a coolwsd restart. For multi-pod setups, open the same document from different users and confirm that all of them land on the same pod. Ask for these test cases to be written into the scope and signed off by the people who will use the system.
How DeployOpen scopes and delivers Collabora Online proxy work
DeployOpen plans, builds and documents the reverse proxy layer for Collabora Online inside your own infrastructure, so routing, TLS and timeouts are agreed before any change reaches production. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- We confirm which proxy you run (Nginx, Apache or HAProxy) and where it sits in your network.
- We agree the written subdomain layout, WOPI host list and TLS termination point before configuration starts.
- We record which paths and WebSocket routes must be forwarded, and which Nextcloud or other WOPI host traffic reaches the server.
How we build
- We write the proxy configuration for your chosen server and test it against a staging coolwsd instance first.
- We check WebSocket upgrades, long editing sessions and timeout values with real document open, edit and save cycles.
- We confirm that WOPISrc-based routing keeps every user editing one document on the same backend when you run multiple servers.
How we hand over
- You receive the tested configuration files, a routing diagram and a record of every timeout and header value chosen.
- We document the verification steps your team can repeat after a proxy or certificate change.
- We walk your operators through the failure modes we tested so they can recognize them in logs.
How we support
- Ongoing support, upgrades and testing after handover are available as a retainer, scoped in writing.
- Proxy changes are retested when Collabora Online or your proxy version changes, with the scope agreed in advance.
- Your team keeps ownership of the infrastructure, and we work inside the cloud accounts, data centers or networks you control.
