Environment variables
All configuration is environment; nothing is baked into the image. Copy
deploy/.env.example to deploy/.env and fill it in.
PostgreSQL (docker-compose.yml only)
Section titled “PostgreSQL (docker-compose.yml only)”| Variable | Example | Description |
|---|---|---|
POSTGRES_USER |
runbook |
The database administrator (a superuser): backups and maintenance only. |
POSTGRES_DB |
runbook |
|
POSTGRES_PASSWORD |
Required. openssl rand -hex 24 | |
RUNBOOK_DB_USER |
runbook_app |
The unprivileged role the server connects as (no superuser, no createdb or createrole); it owns the runbook schema. Created on the volume’s first start (deploy/postgres-init). |
RUNBOOK_DB_PASSWORD |
Required. URL-safe characters only (it is placed inside DATABASE_URL): openssl rand -hex 24 |
External database (docker-compose.external-db.yml only)
Section titled “External database (docker-compose.external-db.yml only)”| Variable | Example | Description |
|---|---|---|
DATABASE_URL |
PostgreSQL 14+; the server creates and migrates the runbook schema. sslmode has libpq’s meaning (deploy/platforms.md, “Database URLs”): verify-full checks the certificate and host name; require only encrypts. |
Server
Section titled “Server”| Variable | Example | Description |
|---|---|---|
RUNBOOK_WEBHOOK_SECRET_KEY |
Required. Seals webhook subscription secrets at rest: 32 random bytes, base64. Generate once and keep it; losing it makes stored webhook secrets unreadable (rotate the subscriptions then). openssl rand -base64 32 | |
RUNBOOK_ORIGIN |
http://localhost:8080 |
The public URL users and the CLI reach the server at (scheme://host[:port], no path). Behind a TLS proxy this is the https:// URL. A plain http:// origin on a non-loopback host makes serve print a warning at startup: bearer tokens would cross the network unencrypted. |
RUNBOOK_BIND_ADDRESS |
127.0.0.1 |
Host interface and port the server is published on. Loopback by default; set RUNBOOK_BIND_ADDRESS=0.0.0.0 only behind a firewall or TLS proxy. |
RUNBOOK_HOST_PORT |
8080 |
|
RUNBOOK_TRUSTED_PROXIES |
The reverse proxies whose X-Forwarded-For (or Forwarded) header names the client: a comma list of addresses or CIDR blocks; empty trusts none, and every client then shares the proxy’s address in the per-IP sign-in limits. With a TLS proxy on this host in front of the loopback port, connections reach the container from the Docker bridge gateway, so trust the bridge (for example 172.16.0.0/12). Trust a proxy only when nothing else can reach the published port: a trusted peer may claim any client address. | |
RUNBOOK_ALLOW_PRIVATE_WEBHOOK_TARGETS |
false |
Webhook targets on private, loopback or plain-http addresses (self-hosted receivers on the same network). Link-local (cloud metadata) needs its own flag. |
RUNBOOK_ALLOW_LINK_LOCAL_WEBHOOK_TARGETS |
false |
|
RUNBOOK_WEB_DIR |
The web UI the image ships, served on RUNBOOK_ORIGIN (open it in a browser). On by default; uncomment to serve the API alone. |
Sign-in (D48)
Section titled “Sign-in (D48)”| Variable | Example | Description |
|---|---|---|
RUNBOOK_AUTH_SECRET |
People sign in with a one-time email code or with Google; there are no passwords. Sign-in is off until RUNBOOK_AUTH_SECRET is set; the server and the bootstrap token (seed-first-token.sh) still work without it. Required to enable any method: 32+ random characters. openssl rand -hex 32 | |
RUNBOOK_AUTH_METHODS |
Which methods are on: email, google or both (comma list). Empty means every method configured below. | |
RUNBOOK_AUTH_ALLOWED_DOMAINS |
Email domains allowed to sign in (comma list, exact match); empty means any. | |
RUNBOOK_SMTP_URL |
Email codes: an SMTP relay, credentials in the URL (smtps:// for implicit TLS), and the From address. Both are needed for email codes. | |
RUNBOOK_SMTP_FROM |
Email codes: an SMTP relay, credentials in the URL (smtps:// for implicit TLS), and the From address. Both are needed for email codes. RUNBOOK_SMTP_FROM=The Runbook <login@example.test> | |
RUNBOOK_GOOGLE_CLIENT_ID |
Google: an OAuth web client whose redirect URI is {RUNBOOK_ORIGIN}/api/auth/callback/google. Both or neither. | |
RUNBOOK_GOOGLE_CLIENT_SECRET |
Evidence uploads (D49–D51)
Section titled “Evidence uploads (D49–D51)”| Variable | Example | Description |
|---|---|---|
RUNBOOK_UPLOAD_SIGNING_KEY |
Photos, screenshots and files attached to steps. Off until both values are set. User files are served from a separate origin so a malicious file can never act as the app: use another domain than RUNBOOK_ORIGIN (ideally not a subdomain of it; never the same host name on another port, as cookies ignore ports), routed by your TLS proxy to RUNBOOK_USERCONTENT_HOST_PORT. Signing key for upload and file URLs: 32 random bytes, base64. openssl rand -base64 32 | |
RUNBOOK_USERCONTENT_ORIGIN |
||
RUNBOOK_USERCONTENT_HOST_PORT |
8081 |
Host port of the user-content listener (published on RUNBOOK_BIND_ADDRESS). |
Theme colours (UI-1)
Section titled “Theme colours (UI-1)”| Variable | Example | Description |
|---|---|---|
RUNBOOK_THEME_ACCENT |
Override the web app’s accent colours, each #rrggbb (either case; #rgb and colour names are refused). /v1/meta reports them as theme. The first two apply to both the light and the dark theme; a DARK value replaces its base value in the dark theme only. Empty means the app’s own colours. A value that is not #rrggbb refuses startup (config.invalid_theme_color naming the variable); a colour below WCAG AA contrast (4.5:1 against #ffffff, or the dark background #14133a) only logs a warning at startup. |
|
RUNBOOK_THEME_ACCENT_SECONDARY |
Override the web app’s accent colours, each #rrggbb (either case; #rgb and colour names are refused). /v1/meta reports them as theme. The first two apply to both the light and the dark theme; a DARK value replaces its base value in the dark theme only. Empty means the app’s own colours. A value that is not #rrggbb refuses startup (config.invalid_theme_color naming the variable); a colour below WCAG AA contrast (4.5:1 against #ffffff, or the dark background #14133a) only logs a warning at startup. |
|
RUNBOOK_THEME_DARK_ACCENT |
Override the web app’s accent colours, each #rrggbb (either case; #rgb and colour names are refused). /v1/meta reports them as theme. The first two apply to both the light and the dark theme; a DARK value replaces its base value in the dark theme only. Empty means the app’s own colours. A value that is not #rrggbb refuses startup (config.invalid_theme_color naming the variable); a colour below WCAG AA contrast (4.5:1 against #ffffff, or the dark background #14133a) only logs a warning at startup. |
|
RUNBOOK_THEME_DARK_ACCENT_SECONDARY |
Override the web app’s accent colours, each #rrggbb (either case; #rgb and colour names are refused). /v1/meta reports them as theme. The first two apply to both the light and the dark theme; a DARK value replaces its base value in the dark theme only. Empty means the app’s own colours. A value that is not #rrggbb refuses startup (config.invalid_theme_color naming the variable); a colour below WCAG AA contrast (4.5:1 against #ffffff, or the dark background #14133a) only logs a warning at startup. |
|
RUNBOOK_MEMORY_LIMIT |
Memory caps (compose also caps each container at 200 processes). | |
POSTGRES_MEMORY_LIMIT |
Memory caps (compose also caps each container at 200 processes). |
Platform (deploy/platforms.md)
Section titled “Platform (deploy/platforms.md)”| Variable | Example | Description |
|---|---|---|
RUNBOOK_LOG_FORMAT |
These go in the server’s environment: (compose) or the platform’s settings. one JSON object per log line on stdout |
|
RUNBOOK_DATABASE_POOL_SIZE |
server connections per instance | |
RUNBOOK_AUTH_DATABASE_POOL_SIZE |
sign-in service connections per instance | |
RUNBOOK_SHUTDOWN_TIMEOUT_SECS |
longest stop after SIGTERM | |
RUNBOOK_IMAGE |
runbook-pilot:local |
Image tag compose builds and runs. |
Also read by the server
Section titled “Also read by the server”These are read by the server but aren’t in deploy/.env.example.
The operating guides
describes most of them.
| Variable | Read in |
|---|---|
DATABASE_URL_DIRECT |
crates/runbook-store-postgres/src/config.rs |
RUNBOOK_ALLOW_NEWER_SCHEMA |
crates/runbook-store-postgres/src/config.rs |
RUNBOOK_AUTH_CAN_REGISTER_URL |
crates/runbook-server/src/auth_child.rs |
RUNBOOK_AUTH_COMMAND |
crates/runbook-server/src/config.rs |
RUNBOOK_AUTH_EMAIL_TRANSPORT |
crates/runbook-server/src/auth_child.rs |
RUNBOOK_AUTH_INTERNAL_SECRET |
crates/runbook-server/src/auth_child.rs |
RUNBOOK_AUTH_MIGRATIONS_DIR |
crates/runbook-server/src/auth_child.rs |
RUNBOOK_AUTH_PORT |
crates/runbook-server/src/auth_child.rs |
RUNBOOK_BLOB_BUCKET |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_BLOB_PREFIX |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_BLOB_STORE |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_BLOB_SWEEP_AGE_SECS |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_BLOB_SWEEP_INTERVAL_SECS |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_LIMIT_EXECUTIONS_MONTHLY |
crates/runbook-store-postgres/src/config.rs |
RUNBOOK_LIMIT_RUN_BYTES |
crates/runbook-store-postgres/src/config.rs |
RUNBOOK_LIMIT_STEP_RUNS |
crates/runbook-store-postgres/src/config.rs |
RUNBOOK_LISTEN_ADDR |
crates/runbook-server/src/config.rs |
RUNBOOK_LISTEN_PORT_FROM_ENV |
crates/runbook-server/src/config.rs |
RUNBOOK_MAX_CONNECTIONS |
crates/runbook-server/src/config.rs |
RUNBOOK_MAX_REQUEST_BYTES |
crates/runbook-server/src/config.rs |
RUNBOOK_MAX_SKILL_BYTES |
crates/runbook-server/src/config.rs |
RUNBOOK_MAX_SOURCE_BYTES |
crates/runbook-server/src/config.rs |
RUNBOOK_MIGRATE_ON_START |
crates/runbook-server/src/config.rs |
RUNBOOK_RETENTION_ARCHIVE_DAYS |
crates/runbook-server/src/config.rs |
RUNBOOK_RETENTION_LIVE_DAYS |
crates/runbook-server/src/config.rs |
RUNBOOK_RETENTION_PROJECT_OVERRIDES |
crates/runbook-server/src/config.rs |
RUNBOOK_RETENTION_SUMMARY_DAYS |
crates/runbook-server/src/config.rs |
RUNBOOK_ROLLBACK_FLOOR |
crates/runbook-server/src/lib.rs |
RUNBOOK_S3_ENDPOINT |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_S3_FORCE_PATH_STYLE |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_S3_REGION |
crates/runbook-store-objects/src/config.rs |
RUNBOOK_SLACK_BOT_TOKEN |
crates/runbook-core/src/slack.rs |
RUNBOOK_SLACK_DEFAULT_CHANNEL |
crates/runbook-core/src/slack.rs |
RUNBOOK_SLACK_SIGNING_SECRET |
crates/runbook-core/src/slack.rs |
RUNBOOK_USERCONTENT_LISTEN_ADDR |
crates/runbook-server/src/config.rs |
RUNBOOK_WEBHOOK_PREVIOUS_SECRET_KEYS |
crates/runbook-server/src/config.rs |