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

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

  1. 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.
  2. Get the licence — Request it for that ID (see Licensing).
  3. Write the setup file — The same sections as the wizard; secrets as ${VARIABLE} references.
  4. 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.
  5. 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
KeyRequiredMeaning
database.urlWhen DATABASE_URL isn't setPostgreSQL URL; query options such as sslmode and pool_max_conns are kept
cache.redis_urlFor a clusterRedis URL: one server, Sentinel or Redis Cluster
storage.backendYeslocal, s3, minio or azure; only that backend's section is read
storage.s3.*With s3bucket, region; access_key and secret_key (or neither, for the IAM role); optional role_arn, external_id
license.file or license.dataYes, one of themThe licence JSON: a file (relative to the setup file) or inline
admin.email, admin.name, admin.passwordYesThe 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

FlagWhat it does
--setup-config <file>Set up a fresh installation from this file (overrides SETUP_CONFIG_FILE)
--machine-idPrint 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