Configuration

Docket loads configuration from a TOML file, environment variables, and CLI flags. Precedence (highest to lowest):

1. CLI flags
2. Environment variables (prefix DOCKET_, double-underscore for nesting, e.g. DOCKET_SERVER__PORT)
3. Config file
4. Built-in defaults

Runtime overrides from the admin UI

For keys marked Editable in UI in the Configuration reference, values set from /admin/config are persisted to Postgres (config_entries) and layered on top of file/env at request time. The precedence list above describes how the base value is resolved at startup; admin-UI overrides apply on top of that base. Whether a saved change takes effect immediately or only after a process restart is shown per-key in the reference under When UI change takes effect.

Config file search

The config file is found via, in order:

1. --config <path> (or -c <path>)
2. ./docket.toml
3. $XDG_CONFIG_HOME/docket/docket.toml
4. /etc/docket/docket.toml

Start from docket.example.toml in the repo, which documents every option with its default value:

cp docket.example.toml docket.toml

Sections

For the complete key-by-key reference (every option, default, type, whether it’s editable from the admin UI, and when a UI change takes effect), see Configuration reference — auto-generated from the Go config registry. The annotated TOML lives in docket.example.toml. High-level groups:

Section	What it controls
[server]	HTTP listen address, timeouts, body size limits, CORS, HSTS, CSP
[database]	PostgreSQL URL and connection pool settings
[telemetry]	OpenTelemetry tracing (OTLP endpoint, service name)
[log]	Log level and format
[auth]	Local auth toggle, session timeouts, lockout policy
[[oidc.providers]]	OIDC identity providers (repeatable)
[scim]	SCIM 2.0 provisioning
[storage]	S3-compatible attachment storage (MinIO works for dev)
[security.ssrf]	SSRF protection for outbound requests

Environment variable examples

# Override the database URL
export DOCKET_DATABASE__URL="postgres://docket:secret@db:5432/docket?sslmode=require"

# Listen on a non-default port
export DOCKET_SERVER__PORT="9090"

# Enable OpenTelemetry
export DOCKET_TELEMETRY__ENABLED="true"
export DOCKET_TELEMETRY__OTLP_ENDPOINT="otel-collector:4317"

Double-underscores (__) map to nested TOML keys. For example, DOCKET_AUTH__SESSION_IDLE_TIMEOUT="1h" maps to [auth] session_idle_timeout = "1h".

Production checklist

• Set [server].allowed_hosts and [server].allowed_origins explicitly — empty values are development-mode escapes.
• Set [server].hsts_enabled = true when behind TLS termination.
• Use a strong [scim].bearer_token if SCIM is enabled.
• Use a managed database with backups (or follow Backup & restore).
• Keep [security.ssrf].enabled = true unless you have a specific outbound-CIDR exception.
• In scaled deployments, set [database].auto_migrate = false and apply migrations from a single pre-deploy step (docket migrate up) so rolling pods don’t race; serve will refuse to start until the DB is current. See the CLI reference.
• If you’re swapping [ai.embedding].provider or [ai.embedding].model in a production environment, set [ai.embedding].auto_migrate = false first to defer the re-embedding pass to a maintenance window. Watch progress with docket embedding status.