Skip to content

Environment variables

All configuration is environment; nothing is baked into the image. Copy deploy/.env.example to deploy/.env and fill it in.

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.
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.
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
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).
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).
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.

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