How to Configure Idle Timeouts for Collabora Editing Sessions

Collabora Online has several settings that sound like an “idle timeout,” but they control different behavior. If an editor dims or stops updating while a user is still working, adjust the per-view inactivity setting. If a document stays loaded after everyone leaves, adjust the per-document timeout. If the editor actually disconnects, check the reverse proxy’s WebSocket timeout before changing Collabora’s idle policy.

The current Collabora Online configuration template documents a 15-minute per-view idle timeout, a 5-minute timeout when the browser tab is out of focus, and a one-hour timeout before an idle document is unloaded. These defaults can vary by release and packaging, so inspect the configuration shipped with your installed version before making changes. The values below refer to the current template checked for this guide, not a guarantee for every CODE or enterprise deployment.

Choose the setting based on the behavior you want

Collabora documents the meanings and defaults in its current coolwsd configuration template and configuration reference. A per-view idle timeout is not the same as closing an account or revoking access: it dims the view and stops updates. A per-document timeout unloads an idle document process; it is not a timer that should terminate a person who is actively editing.

Recommended starting points

• Keep users’ active tabs from dimming too soon: increase per_view.idle_timeout_secs from the installed default to a measured interval such as 1,800 seconds (30 minutes). This is a practical starting point, not a universal recommendation.
• Allow people to switch tabs while keeping a document fresh: raise per_view.out_of_focus_timeout_secs separately. Do not increase it just because users are inactive in a focused tab.
• Reduce memory use after documents are abandoned: leave the per-view values alone and consider lowering per_document.idle_timeout_secs, after confirming the document is actually idle and that storage saves are healthy.
• Fix a fixed-time disconnect: investigate the proxy, ingress, or load balancer’s WebSocket timeout. Changing the per-view dimming setting will not repair a WebSocket that the proxy closes.
• Preserve frequent saves: leave the idle-save and autosave values at their current settings unless you have a separate reason to change them.

Change the settings in coolwsd.xml

For a package-based installation, find the active coolwsd.xml file used by the running service. Common locations include /etc/coolwsd/coolwsd.xml, but paths vary across distributions and older releases. Do not assume that editing a sample file or an unused mounted copy changes the running service.

Back up the active file, then edit only the relevant values under the existing <per_view> and <per_document> sections. For example, this excerpt sets a 30-minute inactive-user timeout, a 15-minute background-tab timeout, and a two-hour idle-document unload:

<per_view>
    <idle_timeout_secs>1800</idle_timeout_secs>
    <out_of_focus_timeout_secs>900</out_of_focus_timeout_secs>
</per_view>
<per_document>
    <idle_timeout_secs>7200</idle_timeout_secs>
</per_document>

This is an excerpt, not a complete replacement configuration. Preserve the attributes, comments, nesting, and other elements in the file shipped with your version; some builds expect additional XML attributes. If you only want to change dimming while the tab remains focused, edit only the per-view idle value. Raising both per-view values and the document unload value at once makes it harder to learn which setting addressed the complaint.

Validate the XML using your deployment’s supported configuration tooling, then restart or reload Collabora using the method documented for that package. Watch the startup logs for configuration parse errors and confirm that the running process loaded the intended file. A setting change that is not present in the active process will have no effect.

Set the same options in Docker or Kubernetes

In Collabora’s Docker image, administrators commonly pass configuration options through extra_params using the --o: option syntax. The following Compose-style value illustrates the same example:

extra_params=--o:per_view.idle_timeout_secs=1800 --o:per_view.out_of_focus_timeout_secs=900 --o:per_document.idle_timeout_secs=7200

Use this only if your image and deployment chart support extra_params. For Kubernetes, Helm, or an operator-managed installation, put the options in the chart or custom resource’s supported configuration field rather than editing a generated container file. When changing environment variables in Compose, recreate or redeploy the service so the new values reach the container; a plain restart may reuse the existing container configuration.

Do not set the same option in conflicting places, such as both a mounted XML file and an environment parameter, without checking the precedence rules for that release. After redeployment, inspect the container startup logs and the active configuration. The Collabora project’s source repository and version-matched deployment documentation are the appropriate references when option names or container behavior differ.

Check reverse-proxy timeouts separately

Collabora’s editor uses WebSockets for ongoing browser communication. A proxy can close an otherwise valid WebSocket even while the Collabora document and view timeouts are set much longer. In that case, users may see a disconnection, reconnect prompt, or an editor that stops receiving updates rather than a simple dimmed view.

Compare the proxy’s read/send timeout, any ingress or cloud load-balancer idle timeout, and Collabora’s intended session behavior. The timeouts must be compatible along the whole route. Collabora’s proxy settings guide includes WebSocket proxy configuration and long-lived connection examples. Apply the guidance appropriate to your exact proxy and release; do not copy an old Nginx block blindly into a different proxy or an unrelated route.

A useful clue is the pattern of failure. If users only see the inactive view dim, examine per_view. If all users disconnect at roughly the same elapsed time, inspect proxy and load-balancer logs at that timestamp. If a document closes only after all participants leave, the per-document timeout is more relevant.

Test one timeout at a time

1. Record the current values from the active configuration and note your Collabora version and deployment method.
2. Open a test document with two users or two browser sessions so you can observe both an active and an inactive view.
3. Change only the timeout that matches the symptom. For example, to prevent dimming in a focused but quiet tab, adjust per_view.idle_timeout_secs only.
4. Restart or redeploy through the supported method, then confirm the new value appears in the active configuration or startup logs.
5. Wait beyond the previous threshold. Confirm whether the view still dims, the second user still receives updates, and edits continue to save.
6. Close all views of the test document and observe whether the idle document unloads within the intended range.
7. Check Collabora and proxy logs for WebSocket closure, XML parse errors, failed saves, or unexpected process cleanup.

Do not test the change on an unsaved production document. Confirm that modified files save to the storage backend before allowing an idle document process to unload. If the issue is only noticed with unsaved changes, check autosave and storage errors as a separate problem rather than lengthening every timeout.

Balance convenience, resource use, and reliability

Longer per-view timeouts suit teams that review documents in pauses or work across several browser tabs. Shorter values can make inactive views stop updating sooner, which may reduce background activity, but they can interrupt a reader who is still looking at the document. The per-document timeout is a separate resource-management choice: extending it keeps unused documents loaded longer, while shortening it may require a fresh load when a user returns.

For most deployments, change the smallest number of settings needed to match the observed behavior. Preserve save intervals, set a reasonable per-view inactivity window for the team, keep the background-tab timeout intentional, and tune proxy WebSocket limits only when logs or timing indicate a connection-layer problem. Recheck the installed version’s configuration template after upgrades because defaults and supported settings can change.