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

Setup wizard

Set up a new installation step by step: licence, database, storage, cache and the first administrator

A server that has never been set up starts in setup mode: it serves only the setup wizard, protected by a one-time setup key. The wizard collects what the installation needs, stores every credential encrypted in the database, and restarts the server into normal mode. It takes about five minutes once PostgreSQL and your storage exist.

Setup wizard, License: the installation ID to request a licence with, and the licence to upload or paste
Setup wizard, License: the installation ID to request a licence with, and the licence to upload or paste

1. Before you start

You needDetails
A PostgreSQL databaseAn empty database and a role that owns it. Not a superuser. See Plan an installation.
File storageA directory on the server, an S3 bucket, a MinIO bucket or an Azure Blob container, which must already exist.
Redis (optional)Needed only for a cluster.
CONFIG_ENCRYPTION_KEYSet on the server before its first start, and kept safe.
A licenceBound to the installation ID the wizard shows on its first step. See Licensing.

2. Open the wizard

  1. Start the server — With DATABASE_URL and CONFIG_ENCRYPTION_KEY set (see Install the Wiki).
  2. Find the setup link — The log prints a line like open the setup wizard … setup_url=https://wiki.example.com/setup?token=….
  3. Open it — The page reads the key and removes it from the address bar.
  4. Choose your language — The language menu at the top. The first administrator keeps it as their language.

3. The steps

StepWhat it asks
1. LicenseShows the Installation ID (Copy installation ID). Upload file or Paste text, then Validate license. Next stays off until the licence is valid for this installation
2. DatabaseA Connection string or Connection details (host, port, database, user, password, SSL mode). Test connection checks that the Wiki can sign in and create tables; a database that already holds tables is flagged, with Wipe database for one you made for the Wiki
3. StorageLocal filesystem (a base path), AWS S3 (bucket, region, keys or the server's IAM role), MinIO or Azure Blob Storage. The wizard writes and reads a test object before you go on
4. CacheAn optional Redis URL; leave it empty for a single server
5. AdministratorThe first super admin's name, email and password, or Restore from a backup
Setup wizard, Administrator: the first super admin, or restore from a backup
Setup wizard, Administrator: the first super admin, or restore from a backup

Complete setup saves everything, runs the database migrations and restarts the server in normal mode. The page waits and then takes you to sign-in. Nothing is saved until Complete setup succeeds, so you can restart the server and begin again at any point before that.

Setup never changes an installation that exists: when the database already holds one, this server only joins it as one more server (with that installation's CONFIG_ENCRYPTION_KEY), and what you entered isn't applied.

4. After setup

  1. Sign in — As the administrator you created.
  2. Set the Wiki's address — Settings → General: the address people use. Links in emails and single sign-on depend on it.
  3. Configure email — Settings → Application → Email, so invitations and password resets work. See Email.
  4. Bring people in — Directories, single sign-on or invitations. See Users & directories.
  5. Create the first spaces — Only super admins create spaces. See Spaces.
  6. Turn on backups — Settings → Backups. See Backups.
  7. Harden it — Work through the production checklist.

5. If setup fails

What you seeWhat to do
The setup page says the key is missing or wrongOpen the exact setup_url from the newest log line; the key changes on every restart unless SETUP_TOKEN is set
Database: can't connect or can't create tablesCheck host, port and SSL mode; the role needs to own the database
Storage isn't accessibleThe bucket or container must exist; check the credentials, region or endpoint, and that the server can reach it
Couldn't connect to RedisCheck the URL scheme for Sentinel or Cluster, the password and TLS (rediss)