Skip to content

Install and configure

The quick starts get a server running in minutes. This page is the reference behind them: what every install needs, and the settings you’ll want before real use.

Setting Docker/Kubernetes Cloudflare Why
Public origin RUNBOOK_ORIGIN ORIGIN (api), RUNBOOK_ORIGIN (sign-in) Links, cookies, CSRF and OAuth all use it. scheme://host[:port], no path
Database DATABASE_URL (PostgreSQL 14+) D1, Durable Objects, R2 bindings State
Webhook sealing key RUNBOOK_WEBHOOK_SECRET_KEY WEBHOOK_SECRET_KEY secret Encrypts webhook signing secrets at rest. 32 random bytes, base64. Keep it with your backups
Sign-in RUNBOOK_AUTH_SECRET and an email or Google method The sign-in Worker’s RUNBOOK_AUTH_SECRET People sign in. Without it, only tokens work
First owner runbook-server bootstrap POST /internal/bootstrap with BOOTSTRAP_SECRET Creates the organization, its owner and the default project

Every setting of the container edition is in Environment variables, generated from the server’s source.

Terminal window
cp deploy/.env.example deploy/.env && chmod 600 deploy/.env
# fill in deploy/.env, then:
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build --wait
docker compose -f deploy/docker-compose.yml --env-file deploy/.env exec server runbook-server doctor

The compose file runs the server and PostgreSQL, with the server connecting as an unprivileged role. For a database you run elsewhere, use deploy/docker-compose.external-db.yml with DATABASE_URL. Full steps: Quick start with Docker.

Terminate TLS in a reverse proxy and set RUNBOOK_ORIGIN to its https:// URL. Tell the server which proxies to trust, so per-client limits (sign-in codes, device logins) see the real client:

Terminal window
RUNBOOK_TRUSTED_PROXIES=10.0.0.0/8,::1

The client is then the right-most X-Forwarded-For hop that isn’t a trusted proxy. Without it, every client behind the proxy shares one set of limits. Trust a proxy only if nothing else can reach the server’s port.

Files and screenshots attached to steps are off until you give them their own origin, so a malicious upload can never act as the app:

Docker/Kubernetes Cloudflare
RUNBOOK_UPLOAD_SIGNING_KEY RUNBOOK_UPLOAD_SIGNING_KEY secret 32 random bytes, base64; signs upload and file URLs
RUNBOOK_USERCONTENT_ORIGIN RUNBOOK_USERCONTENT_ORIGIN var A different host name, ideally on a separate registrable domain
RUNBOOK_USERCONTENT_LISTEN_ADDR (optional) A custom domain on the api Worker Where that origin is served

User content is served with Content-Security-Policy: sandbox, nosniff and no cookies. Images are re-encoded at upload, which strips EXIF and GPS data. /v1/meta reports capabilities.uploads: true once both are set.

Set the web app’s accent colours (#rrggbb) to your own:

Terminal window
RUNBOOK_THEME_ACCENT='#0f766e'
RUNBOOK_THEME_ACCENT_SECONDARY='#f59e0b'
RUNBOOK_THEME_DARK_ACCENT='#5eead4' # optional, dark theme only

An invalid value stops serve from starting (config.invalid_theme_color); on Cloudflare it’s logged and the default theme is served.

Terminal window
runbook-server bootstrap --owner-email you@example.com --owner-name "Your Name"

A local command on the server host, never an HTTP route. It runs once per database and prints the organization, owner and project IDs; the owner then signs in with a code sent to that address. --with-token also prints an owner token and a project service token, once. Without sign-in configured, plain bootstrap prints both tokens.

Terminal window
runbook-server doctor # database, schema version, blob store
curl -s https://runbooks.example.com/v1/meta # version, schema, capabilities
runbook login https://runbooks.example.com
runbook whoami