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.
Update with Docker
Connect to your server and run the update script from the deployment folder:- 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.
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
helm-diff plugin. Without it, helm upgrade --dry-run shows the rendered result.2
Upgrade
3
Watch the rollout
--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.After the update
Open Collabase in a browser and confirm it loads. Check the health address, which reports the version: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.
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 For Kubernetes and Swarm, restore the dump you took before the update. See Backup & Restore.
deployment/docker/backups/, named with the time of the update, and restore it: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
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
Related pages
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.