Why an old loolwsd install needs a planned upgrade
If your server still runs 6.4 or earlier loolwsd packages behind a WOPI host such as Nextcloud, plan the move to current coolwsd releases as a project. The upgrade includes a rename, a configuration migration and changes to the proxy endpoints, so a simple package bump will not cover it. Before you schedule work, record the installed version, the WOPI host version, the Collabora server URL stored in the host, and the protocol that URL uses. The Nextcloud administration manual recommends that the Collabora server URL use the same protocol as the Nextcloud installation, preferably HTTPS, so mismatches in that setting are a likely source of breakage after the move.
The supported path to the current release runs through the 24.04 and 25.04 branches before 26.04. Collabora announced 26.04 on July 23, 2026, and the 25.04 branch was first released on June 19, 2025. Point releases kept arriving in 2026, with 25.04.13 released on September 21, 2026. That continued maintenance is a reason not to stop on an older branch. For example, 25.04.7.5, released January 29, 2026, fixed CVE-2026-23623, so an installation frozen on an earlier build would be running without that fix. Read the Collabora Online 25.04 release notes before you choose the intermediate step.
Confirm early whether the existing installation came from the free CODE build. Collabora describes CODE as a rolling release suited to testing, home use or small teams, and it is not recommended for production. If your 6.4 system is CODE-based and users depend on it, the upgrade is also the point to decide on a supported subscription, which changes repositories, images and entitlements. Ask your team to identify every document type and integration in use, so the test window can cover real files and not only a clean start page. Those inputs drive the scope, the rollback plan and the effort, and they belong in the written scope before work starts.
What changes between loolwsd 6.4 and current coolwsd releases
This table compares what changed between loolwsd in 6.4 and coolwsd in current branches, with the impact on each area and the action to take before cutover. Items without a supplied release detail are marked to confirm against the release notes for your target version. Read it as a pre-upgrade checklist and assign an owner to each row.
| Area | What changed | Impact on your installation | Action needed |
|---|---|---|---|
| Binary and service rename | The server process moves from loolwsd to coolwsd in the binary, service unit and packaged names. | Scripts, systemd overrides, monitoring checks and health probes that name loolwsd may stop finding the process after the switch. | Inventory every reference to loolwsd, then update units and checks. Confirm exact package and unit names in the release notes for your target version. |
| Configuration file and keys | Settings live in a coolwsd configuration file, and some keys may have been renamed, moved or given new defaults. | Settings copied from the 6.4 file can be silently ignored or conflict with new defaults, including WOPI host and TLS settings. | Diff the old and new configuration, port each key deliberately, and confirm each renamed or removed key against the release notes. |
| Proxy endpoints | Reverse proxies must route the WOPI, websocket and related paths that the current server expects. | Requests to paths that were routed for 6.4 may return errors, and document sessions may fail to open. | Review each proxy rule against the current endpoint list in the release notes, then test an edit session through the proxy before cutover. |
| Cool service user and ownership | The service runs under a dedicated cool user, and files it reads or writes must be owned or readable by that account (to confirm for your version). | A service that still runs as an older account or owns files from the old layout can fail to start or fail to save documents. | Confirm the account the new unit runs as, then check ownership of configuration, cache, jail and document directories. |
| File permission checks | Newer releases may check permissions on directories and files at startup and refuse to run when checks fail (to confirm). | Restrictive modes copied from a 6.4 host can block startup, and errors may appear only in logs. | Run a permission audit on the target host before go-live and read the startup log for permission warnings. |
| Security fix in 25.04.7.5 | Collabora's advisory record lists CVE-2026-23623 as fixed in 25.04.7.5, released January 29, 2026. | Installations on 25.04 builds older than 25.04.7.5 carry a known fixed vulnerability. | Confirm your installed build number and move to 25.04.7.5 or later, or to a newer branch, as part of the upgrade plan. |
| Package signing keys | Collabora updated the signing keys for RPM and DEB packages. | Package installs or updates can fail signature checks if the host still trusts the old key. | Import the updated keys from Collabora's published instructions and confirm the repository key fingerprints before updating packages. |
Choosing the supported upgrade path from 6.4
Step through the supported branches, 24.04 and then 25.04, before landing on 26.04, rather than jumping straight to the newest build. A 6.4 or older installation carries years of accumulated configuration, and the rename from loolwsd to coolwsd, the move to new proxy endpoints and the checks on the cool service user and file permissions each change something the server depends on. Moving one branch at a time gives you a known-good state to test against at each stage, so a failure can be traced to one change instead of a stack of them. The 26.04 release was announced on July 23, 2026, according to the Collabora Online forum post, which means teams starting now will land on a branch that was recently released. A direct move is worth testing only when you have a clean staging copy, a full set of representative documents and a rollback plan you have actually rehearsed.
The AI assistant in 26.04 is a reason to slow down at the final step, not a reason to skip the path. According to the release announcement, the assistant covers Writer, Calc and Impress, is off by default, and lets administrators choose the AI provider and whether it runs externally or on their own infrastructure. Because it is disabled out of the box, the upgrade itself will not switch it on, but your team should record that the feature exists and decide whether it is permitted in your environment before anyone enables it. Confirm the exact configuration keys and any data-handling implications with Collabora's 26.04 documentation before the upgrade window, and treat that review as its own work item with a named owner.
What to inventory and back up before touching loolwsd
Before any package or configuration change, the 6.4-era installation needs a written inventory and a restorable copy. The cards below cover the items most often missed when loolwsd is renamed to coolwsd and the proxy and file permissions change underneath it.
Full configuration and certificate backup
Copy the loolwsd configuration directory, the certificate and key files used for TLS, and any systemd or service overrides. Record the exact WOPI allow list (the storage.wopi section in the configuration) and the admin console credentials location. The migration rewrites paths and file names, so a copy taken before the first package change is the only clean way back. Confirm that the backup is readable by someone other than the original installer.
Proxy rules and WOPI host URLs
List every reverse proxy location block that forwards to loolwsd, including the paths for the WOPI endpoints, the discovery route and the websocket path. Record the URL each WOPI host (for example Nextcloud) uses to reach Collabora, and the URL Collabora uses to call back into the host. Newer releases expect updated endpoint paths, so each rule needs a documented old and new form before the proxy is changed.
Fonts, templates and customizations
Inventory any custom fonts installed for rendering, template documents, branding files and changes made to the discovery or admin pages. Fonts installed outside the package manager are easy to lose when the service user or paths change. Check each item against the staging host, and note which customizations the upgrade replaces rather than preserves so they can be reapplied deliberately.
File ownership and permission snapshot
Capture owner, group and mode for the loolwsd data, cache, log and certificate directories, along with the user the service runs as. The move to the cool service user changes who must read and write these paths. Store the snapshot as text output of a recursive listing, so a permission check after the upgrade can be compared line by line against the baseline.
Staging environment matching the WOPI host
Build a staging copy of the Collabora server and the WOPI host at the same versions as production, then restore the backup into it. Test document open, save and co-editing from the host, not only the Collabora admin page. Because the host version affects which WOPI behavior is exercised, the staging host must match production rather than being a newer test build.
Documented rollback target
Write down the exact package version or container tag to return to, where the backup is stored, and the order of steps to restore configuration, certificates and the proxy. Set the criteria that trigger a rollback, such as failed document opens or broken WOPI discovery. Confirm with your vendor or package repository that the old version remains available for installation after the upgrade starts.
How to run the upgrade in order, with rollback points
This sequence moves a 6.4 or earlier loolwsd installation to a current coolwsd release one change at a time, so each change can be reversed before the next one starts. Every step closes with a checkpoint that shows the system still works before you continue.
Freeze and back up the current installation
The administrator records the installed loolwsd package version, copies the configuration directory, TLS certificates, service unit files, reverse proxy configuration and the Nextcloud Office settings, and notes which groups can use or edit documents. Freeze configuration changes for the duration of the upgrade. Rollback checkpoint: if anything later fails, reinstall the recorded package version and restore the copied files. Done when a test document opens and saves on the untouched 6.4 server and the backup has been verified by listing its contents and checking file ownership and permissions.
Stand up a staging server on the target branch
Install the target branch on a separate host or container, using the packages or image that match your chosen release. Do not reuse the old loolwsd directories or service definitions, so the staging host starts from a clean coolwsd layout. Point a non-production Nextcloud instance or test WOPI host at it. Rollback checkpoint: because staging is isolated, rollback means removing the staging host, and production is unaffected. Done when the service starts without errors in its logs, the discovery endpoint answers, and the version reported matches the branch you intended to install.
Migrate configuration from loolwsd names to coolwsd
Carry settings from the old loolwsd configuration file into the coolwsd configuration file on staging, and rename paths and service references that still use the loolwsd name. Check every key against the release notes for the target branch, because keys can be renamed, removed or given new defaults between versions. Confirm that the WOPI host allow list covers the Nextcloud server address and that the server URL uses the same protocol as Nextcloud. Rollback checkpoint: restore the staging configuration from the copy taken in step one. Done when the configuration loads without warnings in the logs and the allow list matches the hosts you expect.
Update reverse proxy endpoints and WebSocket rules
Change the path prefixes the proxy forwards from the old lool endpoints to the cool endpoints used by the current release, and confirm the exact paths against the target branch documentation. Keep WebSocket upgrade headers in place, since collaborative sessions depend on them. Update the Collabora URL in Nextcloud only after the proxy is ready. Keep the old proxy configuration in place but disabled, so it can be restored quickly. Rollback checkpoint: re-enable the old proxy file, restore the previous Nextcloud Collabora URL and reload the proxy. Done when discovery requests and a WebSocket editing session both pass through the new proxy on staging.
Correct file permissions for the cool service user
Confirm that the service runs as the cool user, then change ownership of configuration, certificates, keys, the cache and temporary directories, and any child process directories that still belong to the old loolwsd user. Make certificates and keys readable by the service account only where the release requires it, and keep private keys restricted. Check that the service can write its working directories without relying on root. Rollback checkpoint: restore ownership and modes from the listing captured in step one. Done when the process list shows the cool user, a document opens and saves, and the logs contain no permission denied messages.
Run document and WOPI host tests on staging
Open, edit and save files in Writer, Calc and Impress, using a representative sample of docx, xlsx, pptx, OpenDocument, PDF and CSV files from your own archive. Test two users editing the same document, lock behavior, and the permission groups that control who can use or edit the editor in Nextcloud Office. Compare layout, formulas and embedded objects with the 6.4 output. Rollback checkpoint: a failed test blocks rollout, and production stays on 6.4 while you fix the cause. Done when every test case in your written test plan passes and the results are signed off by the application owner.
Roll the upgrade across production servers
Upgrade one production server at a time, moving sessions off it first if you run several behind a load balancer that routes by the WOPISrc parameter. Apply the same package, configuration, proxy and permission changes you validated on staging, then run the step five and six checks against that server. Keep the previous package and backup until all servers pass. Rollback checkpoint: for each server, reinstall the saved package, restore the backed up configuration and proxy file, and confirm that users can reconnect. Done when every production server reports the target version, serves test documents, and no errors remain in the logs after a full working day of traffic.
How to test documents and integrations before cutover
Before you move users to the new coolwsd server, run one fixed test set from the WOPI host itself, because a server that starts cleanly can still fail when a real document opens. Cover open, edit and save for a docx, an xlsx and a pptx file, plus a PDF and an ODF file, using the same user accounts and the same Nextcloud or other WOPI host version that your users will use after cutover. Confirm that the WOPI host's allow list for the Collabora server URL matches the new endpoints, not the old loolwsd paths, and that the proof key settings agree between the host and the new server. A mismatch in either tends to show up only when a document is opened, so the test must include an actual open and save, not just a login to the admin page.
Record the results in a form that supports a rollback decision. For each file and each action, note the server version, the WOPI host version, the time of the test, whether the document opened, whether the edit saved and reopened with the change, and any warning shown in the browser or the server log. Keep a separate line for each failure with the exact message, because that text is what you will compare against during troubleshooting. Agree in advance who can call a rollback and what result would trigger it, such as any failed save of a shared test document, so the decision does not depend on who is awake during the window.
Keep the old loolwsd package, its configuration file and its service unit available on the server until sign-off, and do not uninstall or overwrite them during the cutover. Save a copy of the current configuration under a dated name, and note the package version so you can reinstall it from your repository or cache if needed. Confirm with your package source how long the old repository and signing keys remain usable, since package signing keys have been updated for some releases. File format fidelity is the one area this test set cannot settle for you: open a sample of your own real documents, especially complex spreadsheets, templated letters and slide decks with embedded media, and compare layout and formulas against the originals before you sign off.
What makes a loolwsd upgrade take longer
How does the number of servers and WOPI hosts affect an upgrade?
Every Collabora Online server and every WOPI host that calls it adds a separate test and rollout path, so the count of each is the first driver to pin down. A single server connected to one Nextcloud instance can be upgraded, tested and rolled back as one unit. Several servers behind a load balancer, or one Collabora Online server serving several WOPI hosts such as Nextcloud and a document management system, need every combination checked. Each host has its own WOPI allow list, its own URL and its own protocol settings, and each must be confirmed after the cutover. Ask your team to list every host URL that points at the service and every server that answers for it before estimating the work. Upgrading documents that are open during a restart also needs a window agreed with each host's users.
Why does custom configuration and scripting slow down the move to coolwsd?
Configuration written for loolwsd does not carry over unchanged, so every local customization must be found, mapped and retested. The migration renames the service and its configuration, and any value set by hand in the old file, such as allowed hosts, TLS options, storage limits or logging, needs an owner who can confirm the intended behavior. Custom shell scripts, cron jobs, systemd overrides, monitoring checks and deployment tooling that reference the old binary name or paths must be found by search, not by memory. The longer the list of local changes, the more time goes into reading the old system and confirming intent. Ask for a written inventory of every file under the configuration and service directories, plus every script that touches Collabora Online.
How does reverse proxy complexity change the upgrade effort?
The reverse proxy decides which URLs reach the server, so a more complicated proxy means more routes to rewrite and more paths to test. Installations that terminate TLS at one proxy, forward WebSocket traffic, serve several hostnames and pass the WOPISrc parameter through to a second tier each require changes to be checked against the new endpoints. Older guides set up paths for the previous service name, and those paths must be reviewed before the new service accepts traffic. Load balancers that route by the WOPISrc parameter, as the Helm chart requires for collaborative editing, need the same review. Ask whether the proxy configuration is in version control, who owns it, and whether a staging proxy exists for testing the new endpoints before production.
Why does file permission clean-up add time to a loolwsd upgrade?
Permission problems often appear only after the new service starts, because the service runs as a dedicated user that must read its configuration and write to its working directories. Older installations may have run under a different account, or files may have been created by an administrator with root ownership during troubleshooting. Each mismatch has to be found, corrected and rechecked, and fixes applied in haste can widen access more than intended. The work includes confirming that the cool service user can read certificates, write logs and cache directories, and that no sensitive file is readable by unrelated accounts. Ask your administrators how many manual changes were made over the years, since each one is a place where permissions may have drifted.
How do custom fonts and templates extend an upgrade?
Custom fonts and document templates change the output of the editor, so they must be tested in the new release before users depend on them. Organizations often install corporate typefaces, branded templates or locale fonts by hand in system directories, and those files may not be present on a fresh host. A document that looks correct in the old service can reflow or substitute fonts after the move, which affects contracts, forms and regulated correspondence. The effort depends on how many fonts are installed, whether they are licensed for server use, and how many templates your users rely on. Ask for an inventory of installed fonts and a set of representative documents to compare before and after the upgrade.
How does the number of branches to step through change the schedule?
Each major branch you skip past brings its own release notes, configuration changes and integration checks, so a server several branches behind has more to review than one close to current. Collabora publishes major branches on a six-monthly cadence and provides point releases within each branch, so the path from 6.4 or earlier to a current release is longer than a single hop. Package signing key changes, advisories and deprecated settings appear in the release notes of each step, and each one must be read and applied. Teams can decide whether to move to an intermediate branch first or go straight to the current one, and that decision changes how many test cycles are needed. Ask the vendor or partner to list every branch in the path and the changes each one introduces before you agree on a plan.
Does the COOL Controller or Kubernetes deployment add extra work?
A Kubernetes deployment adds chart values, image tags, ingress rules and controller settings to the list of things to migrate, so the effort rises with the depth of the cluster setup. Replica counts are set manually because autoscaling breaks collaborative editing, and changing them during an upgrade has to be coordinated with the open documents. Rolling restarts can move active sessions, so the window and the procedure need agreement with the users of each host. Teams that keep cluster configuration in version control can review the diff for each release, which shortens the work. Ask whether the current deployment uses the umbrella chart or hand-written manifests, and whether a non-production cluster can run the same versions for testing.
How DeployOpen scopes and delivers this upgrade
DeployOpen plans and carries out the move from loolwsd-era Collabora Online 6.4 or earlier to a current release inside your own infrastructure. We start from your existing configuration, proxy and permission layout, and the WOPI host integration, so the upgrade changes only what the target release requires.
How we scope
- We inventory the installed version, packages, service names and the loolwsd configuration files currently in use.
- The written scope lists the coolwsd rename, configuration migration, proxy endpoint changes and the cool service user work.
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before any change starts.
How we build
- We run the upgrade first in a non-production environment that mirrors your proxy, WOPI host and file storage.
- We check file permissions and ownership for the cool service user and confirm the service runs without elevated privileges.
- We test representative documents in Writer, Calc and Impress against your WOPI host before any production cutover.
How we hand over
- You receive a written record of each configuration change, the old-to-new mapping and the verification results.
- We document the rollback steps for each stage so your team can return to the previous installation if needed.
- Your team walks through the runbook with us so operators know the new service names, endpoints and checks.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after the initial handover.
- A retainer can cover monitoring of point releases on the target branch and review of security advisories as they are published.
- Ask any provider to confirm in writing who performs the patching, testing and rollback work after handover.
