Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Upgrades & maintenance

Upgrade a single server or a cluster safely, roll back, and plan routine maintenance

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

  1. Read the notes — The changelog for every version between yours and the new one.
  2. Check health — Settings → Advanced → System check shows no problems, and no backup or import is running.
  3. Back up — Run a backup (Settings → Backups) and make sure it's verified. Note the current version (? → About).
  4. Plan the window — A single server is down while it restarts. A cluster needs no downtime.

3. Single server

  1. Stop the server — SIGTERM; it finishes requests and jobs, then exits.
  2. Replace the programs — The server and the web app; keep the data folder and the environment.
  3. Start the server, then the web app — Watch the log until it serves.
  4. Check — About shows the new version; the system check is clean; a page opens and can be edited.

4. Cluster

  1. Upgrade one server — Stop it, replace it, start it.
  2. Watch — Settings → Clustering shows it active on the new version.
  3. Continue — One server at a time.
  4. 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 oftenTask
Daily (automatic)Backups, retention jobs, analytics and import clean-up: see Scheduled jobs
WeeklyThe system check, failed jobs and event deliveries
MonthlyReview super admins, space admins of important spaces, service accounts and long-lived tokens; storage growth
Each releaseUpgrade within a reasonable time
YearlyRehearse 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.