Skip to main content
A Collabase update replaces the application with a new version and applies the database changes that version needs. Every deployment takes a backup or a safety check first, so a failed update leaves your data as it was. This page covers the three deployments and what they share: preparation, verification and rollback.

Before you update

  • Read the release notes of every version between yours and the new one. A change that needs a step from you is listed first, under Breaking changes.
  • Update the test system first, if you have one, and check the features your team relies on.
  • Schedule the update for a quiet time. The application restarts and is unavailable for a few minutes.
  • Tell your team in advance if the downtime matters.
  • Check that you have a current backup you can restore, see Backup & Restore. The update takes its own backup, but a second copy elsewhere is safer.
  • Docker only: at least 2 GB of free disk space for the download.
Do not run install.sh on an existing installation. It would overwrite your configuration. Use the update command of your deployment.

Update with Docker

Connect to your server and run the update script from the deployment folder:
The script works through these stages:
  • Creates a database backup in deployment/docker/backups/. If the backup fails, the update stops and nothing is changed.
  • Downloads the new version.
  • Checks your database against the new version before switching. If the check finds something the new version cannot convert, the update stops, prints what to fix, and your current version keeps running.
  • Restarts all services. When the new version brings database changes, it takes a second backup right before applying them.
  • Waits for the application to come back and confirms it is healthy.
This typically takes 2 to 5 minutes, depending on your connection. Pre-update backups are kept for 7 days and older ones are removed after a successful backup.
Your server has no internet access? Update with an image bundle, see the air-gapped installation and upgrade guide.

Configuration keys

New versions occasionally need new configuration. The update script adds missing keys to .env and generates new secrets itself. If the output warns about new configuration, review .env afterwards.

Update on Kubernetes

Unpack the new release package and run an upgrade with the values file you used for the install. The chart installs the version it belongs to, so the new package moves every image to the new release.
1

Preview the change

This needs the helm-diff plugin. Without it, helm upgrade --dry-run shows the rendered result.
2

Upgrade

A migration job applies the database changes before the new version starts. It first checks that your data can be converted. If the check fails, the upgrade stops and your database stays as it was.
3

Watch the rollout

Use your values file and not --reuse-values. A new chart can add settings, and --reuse-values hides their defaults. With the default single instance, the application restarts and is unavailable for a short time. With S3 file storage and several instances the pods roll without downtime, see Scale out. To get a database dump before every upgrade, turn on backup.enabled in your values file one upgrade ahead, see Back up and restore. Without it, the upgrade takes no automatic backup, so take one yourself first.

Update on Docker Swarm

Unpack the new release package on a manager node and deploy the stack again. Swarm rolls the services and rolls back automatically if a service fails to start.
Take a database backup before you start. The Swarm deployment takes none by itself.

After the update

Open Collabase in a browser and confirm it loads. Check the health address, which reports the version:
As an administrator you see a notice with the new version once, together with a short update report: when the update happened, whether the services are running, and how many apps are installed. Other people see no notice. Anyone can read the version later at the bottom of the Feedback & help menu or on the sign-in page. An update can bring new apps or new versions of installed apps. They appear in the App Store.

Rebuild the semantic search index

If you use semantic search, it can stop returning results after an update that changes the search setup. Entries made by the previous configuration are no longer comparable with the ones the current setup produces, so they are ignored rather than mixed into the results. Keyword search and everything else the assistant does are unaffected. The nightly maintenance pass repairs the index on its own. To have it back the same day, go to Admin → Settings → AI settings → RAG model & pipeline and click Rebuild next to the status panel. It queues everything the index is missing and reports how many items went into the queue. On a large instance the queue takes a while to drain, and search improves as it does.

If the update fails

If the log says the pre-migration check or the pre-migration backup failed, your database was not changed. Return to the previous version, fix what the log names and run the update again. Where the backups taken right before database changes are kept, and how to restore one, is described in Backup & Restore.
If your hosting already snapshots the database before every update, you can turn the pre-migration backup off with COLLABASE_PRE_MIGRATION_BACKUP=off in .env. This applies to Docker. The check still runs. Without a snapshot, keep it on: it is the only backup the automatic nightly update takes.

Roll back an update

A rollback returns to the previous version. If the update applied database changes, the data of the previous version may not match the new schema, so the safest rollback restores the backup taken before the update. Anything entered after the update started is lost in that case.
1

Return to the previous version

Docker:
Kubernetes:
Swarm: deploy the stack again from the previous release package.
2

Restore the database if the update changed it

If the update applied database changes, restore the backup taken before it. For Docker, find it in deployment/docker/backups/, named with the time of the update, and restore it:
For Kubernetes and Swarm, restore the dump you took before the update. See Backup & Restore.
3

Check the result

Open Collabase and check /api/health. The version must be the previous one.
On Kubernetes, helm rollback returns the chart and the images. It does not undo database changes. After an upgrade that migrated the database, restore the dump as well.

Database password on old installations

If your installation was set up before version 0.9.1, the update script stops with an error when the database password is still the default value. Change it:
1

Choose a new password

Pick a strong password and store it in a password manager.
2

Change it in the database

Replace your-new-password with the password you chose.
3

Change it in the configuration

Open deployment/docker/.env and change the POSTGRES_PASSWORD line to your new password.
4

Run the update again

Backup & Restore

How backups work and how to restore them.

System requirements

What your servers or cluster must provide.

Troubleshooting

What to do if something fails.
Last modified on November 5, 2026