The Wiki 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 and applies the migrations; others wait for it.
- Old and new run side by side. Database changes are backward compatible for one release.
- The newest leads. Leadership moves to a server on the highest version.
- Open pages notice. People see A new version is available with Reload and Later.
2. Before you upgrade
- Read the notes — The changelog for every version between yours and the new one.
- Check health — Settings → Advanced → System check shows no problems, and no backup or import 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. A cluster needs no downtime.
3. Single server
- Stop the server — SIGTERM; it finishes requests and jobs, then exits.
- Replace the programs — The server and the web app; keep the data folder and the environment.
- Start the server, then the web app — Watch the log until it serves.
- Check — About shows the new version; the system check is clean; a page opens and can be edited.
4. Cluster
- Upgrade one server — Stop it, replace it, start it.
- Watch — Settings → Clustering shows it active on the new version.
- Continue — One server at a time.
- Upgrade the web apps — They're stateless; roll them after the servers.
5. Rolling back
- Within one release, the previous version can run against the upgraded database: put the previous programs back the same way.
- Further back, restore the backup taken before the upgrade (see Backups). Changes made since the backup are lost.
6. Routine maintenance
| How often | Task |
|---|---|
| Daily (automatic) | Backups, retention jobs, analytics and import clean-up: see Scheduled jobs |
| Weekly | The system check, failed jobs and event deliveries |
| Monthly | Review super admins, space admins of important spaces, service accounts and long-lived tokens; storage growth |
| Each release | Upgrade within a reasonable time |
| Yearly | Rehearse a restore; rotate credentials for storage, email and identity providers; renew the licence |
7. Moving or replacing servers
- A new server joins with CONFIG_ENCRYPTION_KEY and DATABASE_URL; it needs no setup.
- The installation ID is kept in the database, so moving servers with the same database keeps the licence. A new database needs a new licence: see Licensing.