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

Recovery mode

What happens when an installed server can't start, and how to fix it

If an installed server can't start (the database is down, the encryption key is wrong, storage is unreachable, the licence no longer matches) it doesn't just exit. It starts in recovery mode, finds what's wrong, and shows you how to fix it.

1. Open the recovery page

The server log shows a line like open the recovery page … recovery_url=https://…/recovery?token=…. Open that address. The key keeps the diagnostics private; set RECOVERY_TOKEN to choose it. Like the setup key, it is removed from the address bar once the page has read it.

The recovery page: each check, what failed and how to fix it
The recovery page: each check, what failed and how to fix it

2. What it checks

CheckCommon causes
Bootstrap fileThe server was started with a different CONFIG_ENCRYPTION_KEY, or the file is damaged
Database connectionPostgreSQL is down, unreachable, or its credentials changed
Database schemaAn upgrade's migration failed partway
Stored configurationWrong encryption key, or the wrong database
RedisRedis is down or moved
File storageDirectory not writable, bucket missing, credentials expired
LicenceExpired, or issued for another installation ID

3. Fixing it

Each failed check lists ways to fix it. Some can be applied from the page: a new database or Redis URL, a new licence, or running without Redis on a single server. The server tests the change, saves it encrypted, and restarts; the page reloads when it's back.

Recovery never changes data on its own. Repairs such as fixing a failed migration are described, not performed: take a backup first.

The server only enters recovery mode on a machine that was already set up. A brand-new installation always starts the setup wizard.