Upgrades, backups and compatibility
Versions
The Hub and the client have separate version numbers. Each release states the Hub version it needs.
- A published version never changes. Fixes come as new versions.
- The admin console shows the Hub version and its commit. A commit is not a version number.
Upgrade order
- Check the release notes for API, database and update-protocol changes.
- If the new client depends on the new Hub, upgrade and check the Hub first, then the clients.
- If they're compatible and the Hub is healthy, you can upgrade them independently.
Upgrading a client keeps its server address, device identity, sign-in and local data for each Hub.
Before you upgrade the Hub
- Stop dispatching new work and wait for running tasks to finish.
- Back up the database and all file storage from the same point in time. The database and the library must be restored together.
- Back up your private configuration and note the current source version.
The repository includes hub-backend/full_backup.py for a full encrypted backup and hub-backend/db_admin.py for database checks and restores. Practice a restore before you rely on a backup for production.
Upgrade
| Install | Steps |
|---|---|
| Source launcher | Stop it, update the source, run the same python start.py command |
| Docker | python ops/self-host/deploy.py stop, switch to the new source, python ops/self-host/deploy.py up |
| Your own setup | Stop the Hub, deploy the new version, start it with DB_MIGRATION_MODE=auto |
Versioned migrations run at start. If a migration fails, the Hub doesn't report healthy. Don't run two migrations against the same database at once.
Roll back
Restore the matching source version, database, file storage and keys together. An older Hub can't use a database that a newer Hub has migrated.
Client updates
Clients check the Hub they're connected to for new versions. Installers are signed for updates with an Ed25519 key; the Hub's CLIENT_UPDATE_PUBLIC_KEYS setting lists the public keys clients trust. Keep the private signing key out of the Hub and out of the repository.