Run Collabora CODE Behind Nginx with TLS Termination

Documents may stall after you put Collabora CODE behind HTTPS because the proxy and CODE disagree about where TLS ends, or the proxy drops WebSocket traffic. Configure Nginx to present the public certificate, forward to a private CODE listener, and pass the WebSocket routes. The CODE settings are ssl.enable=false and ssl.termination=true.

This example uses Nginx on the Docker host. For a proxy in another container, use the private Docker network instead. See Collabora’s Proxy settings and CODE Docker image guide for version-specific options.

Understand what SSL termination changes

TLS termination means Nginx handles the browser’s HTTPS connection and certificate while CODE uses HTTP on port 9980 behind it. Keep that listener private: bind it to loopback on a single host, or use a private Docker network. If proxy-to-CODE traffic crosses an untrusted network, protect that link with TLS or a tunnel.

Network diagram showing browser HTTPS terminating at Nginx before private HTTP reaches the Collabora CODE container on 127.0.0.1 port 9980
The browser uses HTTPS to Nginx; HTTP is confined to the private link between the proxy and CODE.

Prepare the container and certificate

  1. Choose the public hostname. Create a DNS record such as office.example.com that points to the Nginx proxy. Obtain a certificate for that exact hostname and install its certificate chain and private key on the proxy.
  2. Keep CODE’s port private. For Nginx installed directly on the Docker host, publish the container port only on loopback. In Compose, the relevant mapping is 127.0.0.1:9980:9980. Do not publish 9980:9980 on every host interface unless a firewall and network design explicitly restrict it.
  3. Set CODE’s TLS mode. In the Compose service, add the two options to the CODE configuration. The example below uses an image variable so you can pin the exact tag you have reviewed and tested.
Docker Compose editor showing the Collabora service port bound to 127.0.0.1 on port 9980
Binding to 127.0.0.1 keeps the CODE listener reachable only from the Docker host.
Docker Compose environment setting with ssl.enable=false and ssl.termination=true for Collabora CODE
These options tell CODE that TLS is handled by the reverse proxy.
services:
  collabora:
    image: ${COLLABORA_CODE_IMAGE}
    restart: unless-stopped
    ports:
      - "127.0.0.1:9980:9980"
    environment:
      extra_params: "--o:ssl.enable=false --o:ssl.termination=true"

Set COLLABORA_CODE_IMAGE to a tested, pinned image tag. Keep your WOPI host allowlist and authentication settings; TLS termination does not replace them. If Nginx is another Docker service, omit the host port mapping and proxy to http://collabora:9980 on the shared private network.

Configure Nginx to terminate TLS and proxy CODE traffic

  1. Add the HTTPS virtual host. Put the following locations inside the Nginx server block for the public Collabora hostname. Replace the example hostname and certificate paths. This configuration is for a root-level Collabora URL, not a URL mounted below a path such as /office/.
Nginx configuration snippet with a TLS listener, office.example.com server name, and certificate file paths
Nginx holds the public certificate and listens on HTTPS for the Collabora hostname.
server {
    listen 443 ssl;
    server_name office.example.com;
    ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location ^~ /browser {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/discovery {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    location ^~ /hosting/capabilities {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location ~ ^/cool/(.*)/ws$ {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ^~ /cool/adminws {
        proxy_pass http://127.0.0.1:9980;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 36000s;
    }
    location ~ ^/(c|l)ool {
        proxy_pass http://127.0.0.1:9980;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Forward the editor assets, discovery, and capabilities routes. The /cool/.../ws and /cool/adminws locations need HTTP/1.1 and Upgrade headers so Nginx can tunnel WebSockets; a long read timeout keeps editing sessions open. See Nginx’s WebSocket proxying documentation.

Nginx location blocks forwarding the browser and hosting discovery paths to the private CODE listener
Forward the editor assets, WOPI discovery, and capabilities endpoints to the same CODE listener.
Nginx WebSocket location for the cool path with HTTP 1.1, Upgrade and Connection headers, and a long read timeout
The main WebSocket route needs HTTP/1.1 and the Upgrade headers or the editor may load without becoming usable.
Nginx configuration for the cool admin WebSocket and Collabora cool or lool request paths
Forward the administrative WebSocket and the remaining document transfer routes as well.

Apply the change and check version-sensitive behavior

  1. Validate Nginx before reloading. Run nginx -t. Continue only if Nginx reports that the configuration test is successful; then reload Nginx with your system’s normal service command.
  2. Recreate the CODE container. Apply the Compose change with docker compose up -d collabora. Check the container logs for startup errors and confirm the active configuration includes both SSL options.
Terminal window with the nginx -t command ready to validate the reverse-proxy configuration
Run the syntax test before reloading so a malformed server block does not interrupt other sites.

For version context, Collabora’s repository recorded a report on July 22, 2026 that the built-in coolwsd --probe health check in CODE 26.04.2.2 and later could check HTTPS on port 9980 even when TLS ends at the proxy. This can mark a container unhealthy while the public endpoint responds. Review the issue record for your image tag; test the public endpoint and an editing session before treating health status alone as proof of a TLS failure. Keep health checks unless another monitor replaces them.

Verify HTTPS discovery and a real editing session

Request https://office.example.com/hosting/discovery in a browser or with curl. It should return WOPI discovery XML over HTTPS, with URLs using the public HTTPS hostname. A certificate warning suggests a hostname or certificate issue; HTTP URLs suggest a TLS-mode or forwarded-scheme mismatch; a 502 suggests the proxy cannot reach CODE.

Next, open a test document from the connected WOPI host and confirm editing works. In browser developer tools, the /cool/.../ws request should establish a WebSocket connection. If discovery works but editing hangs, check the WebSocket locations and headers. Confirm the integration allows the WOPI host and points to https://office.example.com.

Successful setup: the certificate is trusted, discovery uses HTTPS, port 9980 remains private, and a test document opens and edits through the WebSocket.

Leave a Comment

Clear Nextcloud’s File Locking Warning with Redis

Enable reliable Nextcloud file locking, choose the right Redis or Valkey backend, and verify the warning clears without risking concurrent file changes.

What It Takes to Target an A+ Nextcloud Security Rating

What It Takes to Target an A+ Nextcloud Security Rating

Fix common Nextcloud scan findings with current updates, HTTPS and HSTS, precise reverse-proxy trust, and checks against the public server.

Automate Consistent Nextcloud Backups with Restic and Cron

Automate Consistent Nextcloud Backups with Restic and Cron

Back up Nextcloud’s files and MariaDB together, schedule encrypted Restic snapshots with cron, and verify recovery without risking the live server.

Enable Nextcloud Server-Side Encryption with Measured Impact

Configure Nextcloud SSE for the storage that needs it, protect encryption keys, and measure transfer and CPU impact before encrypting existing files.

Add Elasticsearch Full-Text Search to Nextcloud

Connect Nextcloud’s file search to Elasticsearch, index document contents, and choose a setup that fits your server and security needs.

Set a Reliable Expiration Policy for Nextcloud Deleted Files

Set a Reliable Expiration Policy for Nextcloud Deleted Files

Configure Nextcloud to remove deleted files after a defined retention period, schedule background jobs reliably, and avoid commands that purge every user’s trash.

Clear Nextcloud’s Missing Database Indexes Warning

Clear Nextcloud’s Missing Database Indexes Warning

Run Nextcloud’s OCC repair safely, preview the database changes, and check why the warning might remain.

Raise Nextcloud’s Web Upload Limit Past 2 GB

Raise Nextcloud’s Web Upload Limit Past 2 GB

Allow larger Nextcloud browser uploads by aligning PHP, Nginx or Apache, temporary storage, and timeout settings—and verify which limit is blocking the file.

Clear Nextcloud’s PHP Memory Warning at the Web Server

Set the PHP memory limit Nextcloud actually uses, restart the right service, and confirm the 512 MB setting in Admin Overview.

Connect an S3-Compatible Bucket to Nextcloud External Storage

Mount a compatible object-storage bucket in Nextcloud using its S3 backend, with the right endpoint, credentials, access scope, and verification steps.