Depotex upgrades in place: a new version starts, migrates the database once, and carries on. In a cluster, servers are upgraded one at a time while the others keep serving.
1. What happens during an upgrade
- Migrations run once. The first new server to start takes a database lock, applies the new version's migrations, and releases it; others wait for it.
- Old and new run side by side. Database changes are backward compatible for one release: servers of the previous version keep working against the upgraded database until they're replaced.
- The newest leads. Leadership moves to a server on the highest version, so new behavior starts on upgraded servers first.
- Open pages notice. People see A new version is available with Reload and Later; nothing reloads on its own.
- Some work is redone in the background. A release may re-inspect artifacts or rebuild search; the release notes say so.
2. Before you upgrade
- Read the notes — The changelog and the security advisories for every version between yours and the new one.
- Check health — Settings → Advanced → System check shows no problems, and no backup or long job is running.
- Back up — Run a backup (Settings → Backups) and make sure it's verified. Note the current version (? → About).
- Plan the window — A single server is down while it restarts (usually under a minute, longer when a release has heavy migrations). A cluster needs no downtime.
3. Single server
- Stop the server — SIGTERM; it finishes requests and jobs, then exits.
- Replace the program or image — Keep the data folder and the environment.
- Start it — Watch the log until it serves; then the web app.
- Check — About shows the new version; the system check is clean; a test download works.
4. Cluster
- Upgrade one server — Stop it, replace it, start it. It migrates the database if it's first.
- Watch — Settings → Clustering shows it active on the new version; the system check is clean.
- Continue — One server at a time. On Kubernetes, helm upgrade with the new image tags does this for you (see Install with Helm).
- Upgrade the web app — Its pods are stateless; roll them after the servers.
5. Rolling back
- Within one release, the previous version can run against the upgraded database: put the previous images back the same way, one server at a time (helm rollback on Kubernetes).
- Further back, or when release notes say a release can't be rolled back, restore the backup taken before the upgrade (see Backups → Restore). Changes made since the backup are lost.
- Tell support what went wrong, with the details from the About dialog.
6. Routine maintenance
| How often | Task |
|---|---|
| Daily (automatic) | Backups, cleanup policies, retention jobs, integrity checks: see Scheduled Jobs |
| Weekly | Look at the system check, failed jobs and event deliveries; test restore (automatic on Enterprise) |
| Monthly | Review super admins, service accounts and long-lived tokens; storage and quota growth; PostgreSQL vacuum and index health |
| Each release | Upgrade within a reasonable time, and at once for a security advisory that affects you |
| Yearly | Rehearse disaster recovery; rotate credentials used for storage, email and identity providers; renew the license |
7. Moving or replacing servers
- A new server joins with CONFIG_ENCRYPTION_KEY and DATABASE_URL; it needs no setup.
- The installation ID the license is bound to is kept in the database, so moving servers to new machines with the same database keeps it. A new database (a fresh installation, or a backup restored into one) has a new ID and needs a license for it: request it before the move (see Licensing). A server whose license doesn't match starts in recovery mode, where a new license can be applied.
- Moving artifacts to another storage location is done in Settings → Storage without downtime (see Storage).