Trace Collabora Connection Failures with coolwsd Logs

For a Collabora Online Development Edition (CODE) container, raise coolwsd logging to debug, make sure the Socket and WebSocket areas are not disabled, then reproduce one failed document open while following the container logs. In Docker Compose, pass the settings through the CODE image’s extra_params environment variable and recreate the service. Use trace only if debug output does not show where the connection stops, and return to the previous level when you finish.

This method fits a Docker or Compose deployment where you can update the container configuration. A native package install uses /etc/coolwsd/coolwsd.xml and its service manager instead. The setting adds diagnostic detail; it does not repair a proxy, WOPI host, certificate, or network problem by itself.

1. Start with one controlled reproduction

Pick one document and note the time you try to open it, the public Collabora URL, and the container or Compose service name. Avoid repeatedly refreshing several files: one attempt makes it easier to line up the browser symptom, proxy log, integration-server log, and coolwsd entries.

Check that the container is running and identify its name:

docker ps --format 'table {.Names}	{.Status}	{.Ports}'

Replace collabora below with the container name shown on your host. Start following output shortly before reproducing the problem:

docker logs --since 2m --follow --timestamps collabora

--follow streams new output, --since limits the initial history, and --timestamps adds Docker timestamps. Docker documents those options in its container logs reference. In Compose, you can use docker compose logs --since=2m --follow collabora, where collabora is the service key.

2. Raise coolwsd to debug for the test

The Collabora configuration schema supports named levels including warning, notice, information, debug, and trace. It also defines disabled_areas; the documented default disables high-verbosity output from Socket and WebSocket, among other areas. This matters for connection troubleshooting: changing the level alone may still leave the most useful handshake details suppressed. These options are documented in the Collabora coolwsd configuration template and the Collabora Online SDK manual (Docker configuration section; checked October 2026).

For the official collabora/code image, add the two options to the service’s existing extra_params value. Preserve any options already required by your installation, such as SSL termination or server name:

services:
  collabora:
    environment:
      extra_params: "--o:logging.level=debug --o:logging.disabled_areas=Admin,Pixel"

The second option leaves Socket and WebSocket available for high-verbosity logging while keeping Admin and Pixel disabled. Do not add those two areas back to the disabled list during this test. The CODE image documentation describes extra_params as a way to pass command-line options to coolwsd. If your deployment uses a mounted configuration file or a vendor-managed image, follow that deployment’s configuration method instead.

Apply the Compose edit by recreating the service:

docker compose up -d --force-recreate collabora

Use your actual Compose service name. For a short-lived container started with docker run, update its run configuration and recreate it with the same volumes, networks, ports, and other options. The CODE manual says the image accepts extra_params at startup; don’t assume changing the environment of an already-created container changes the running coolwsd process.

3. Read the connection in order

Reproduce the failure once and review only that interval. Search the output for terms such as WebSocket, WOPI, ERR, and WRN, then compare timestamps. The exact wording and log areas vary by Collabora version, so treat these as categories to inspect rather than guaranteed literal messages.

• No new coolwsd entries at the test time: the request may not be reaching this container. Check the configured public URL, DNS, load balancer, reverse-proxy access/error logs, and whether you are tailing the correct replica.
• The browser reaches the service but the WebSocket does not stay open: inspect proxy handling of the WebSocket upgrade, forwarded host and scheme, TLS termination, path routing, and idle timeouts. Compare with the browser developer console and proxy logs; coolwsd cannot explain a request that the proxy never forwards.
• A WOPI request appears and fails: check the integration server’s WOPI URL, host allow-list or alias configuration, reachability from the Collabora container, and the integration server’s response. A WOPI error is a separate stage from the browser-to-Collabora WebSocket connection.
• WOPI succeeds but the browser still disconnects: focus next on the WebSocket route and browser-side connection errors. This sequence narrows the search; it does not prove which proxy or network setting is wrong.

If Docker shows no output even though the service is active, check the logging configuration inside the container. Docker’s log command reads the container’s standard output and error streams; an installation configured to write to a file may instead use a path such as /var/log/coolwsd.log, as defined by its configuration. Inspect the actual file rather than assuming that path:

docker exec collabora sh -c 'grep -n -A25 "<logging>" /etc/coolwsd/coolwsd.xml'

If file logging is enabled, use the configured path, for example:

docker exec collabora sh -c 'tail -n 200 /var/log/coolwsd.log'

4. Verify the result and restore normal logging

After the test, run a bounded read to confirm that the intended attempt produced fresh entries:

docker logs --since 5m --timestamps collabora

You have a useful result when you can align the failed open with a coolwsd event or establish that the request never reached this container, then identify which connection stage needs follow-up. If you need to filter output, use a short time window first:

docker logs --since 5m collabora | grep -Ei 'coolwsd|WOPI|WebSocket|ERR|WRN'

Restore the previous logging.level and disabled_areas values, then recreate the service again. Debug and trace levels can produce much more output and may include sensitive operational details. Before sharing logs, redact access tokens, document names, user identifiers, hostnames, and internal addresses. If the service is not the official CODE image, confirm its configuration path and supported parameters with that image’s maintainer.