Set up without the UI
Unattended setup from a YAML file for scripts, containers and configuration management
Everything the setup wizard asks can come from a YAML file instead, so a new installation can be set up by a script, a container entrypoint or configuration management with nobody at a browser.
1. How it works
- Get the installation ID — ./wiki-server --machine-id prints it and exits. Run it on the machine that will run the Wiki: the ID belongs to that machine.
- Get the licence — Request it for that ID (see Licensing).
- Write the setup file — The same sections as the wizard; secrets as ${VARIABLE} references.
- Start the server once with it — --setup-config setup.yaml, or SETUP_CONFIG_FILE=setup.yaml. The server checks the file, sets up, and continues in normal mode.
- Remove the file — It's read only on a fresh installation and ignored afterwards.
chmod 600 setup.yaml
export CONFIG_ENCRYPTION_KEY="$(cat /run/secrets/wiki-encryption-key)"
export DATABASE_URL='postgres://wiki:…@db.internal:5432/wiki?sslmode=verify-full'
export ADMIN_PASSWORD="$(cat /run/secrets/wiki-admin-password)"
./wiki-server --setup-config setup.yaml
2. The setup file
database:
url: ${DATABASE_URL} # may be left out when DATABASE_URL is set
cache:
redis_url: "" # empty: single server without Redis; required for a cluster
storage:
backend: s3 # local | s3 | minio | azure
local:
path: /var/lib/wiki/files
s3:
bucket: my-wiki-files
region: eu-west-1
access_key: ${S3_ACCESS_KEY} # leave both keys out to use the server's IAM role
secret_key: ${S3_SECRET_KEY}
minio:
endpoint: minio.internal:9000
bucket: wiki
use_ssl: true
access_key: ${MINIO_ACCESS_KEY}
secret_key: ${MINIO_SECRET_KEY}
azure:
container: wiki
account: ${AZURE_STORAGE_ACCOUNT}
key: ${AZURE_STORAGE_KEY}
license:
file: license.json # relative to this file; or data: | with the JSON inline
admin:
email: admin@example.com
name: Administrator
password: ${ADMIN_PASSWORD} # at least 8 characters
| Key | Required | Meaning |
|---|
| database.url | When DATABASE_URL isn't set | PostgreSQL URL; query options such as sslmode and pool_max_conns are kept |
| cache.redis_url | For a cluster | Redis URL: one server, Sentinel or Redis Cluster |
| storage.backend | Yes | local, s3, minio or azure; only that backend's section is read |
| storage.s3.* | With s3 | bucket, region; access_key and secret_key (or neither, for the IAM role); optional role_arn, external_id |
| license.file or license.data | Yes, one of them | The licence JSON: a file (relative to the setup file) or inline |
| admin.email, admin.name, admin.password | Yes | The first super admin |
3. Rules the server enforces
- Private file. The file must not be readable by group or others (chmod 600); otherwise the server stops and prints the chmod to run.
- No unknown keys. A misspelled key is an error.
- Secrets from the environment. Any value may use ${NAME}; a referenced variable that isn't set stops the server with its name.
- Fresh installations only. On an installed server the file is ignored.
- Fails loudly. If a value doesn't work, the server stops with an error that says what to fix; nothing is half set up.
4. After setup, without the UI
- Everything in the web app is also an API: GET /api/openapi.json describes every route, its permission and its licence tier. Sign in once to create an API token, or register an OAuth application with a service account.
- Pages can be brought in from Confluence or Markdown with an import once a space exists.
5. Command-line flags
| Flag | What it does |
|---|
| --setup-config <file> | Set up a fresh installation from this file (overrides SETUP_CONFIG_FILE) |
| --machine-id | Print this machine's installation ID, for a licence request, and exit |
| --restore-file <file> | Check a backup archive with no server running; with --yes, restore it, then exit. See Backups |