Configuration

cerbix reads one YAML file at startup, passed with --config <path>. This page lists the sections, the keys an operator usually sets, and how settings saved in the UI take over from the file. Every key, with its default, is in docker/config.example.yaml.

Loading rules

• Strict. An unknown key, a value of the wrong type or a value outside its range stops startup. Range errors name the key and the allowed range. Nothing is clamped or ignored.
• Defaults apply only to keys you omit. A whole section can be omitted.
• --config is required by serve, migrate, reencrypt, adopt-fact-month and enqueue-service-repair. See the CLI reference.

Environment variables

${VAR} and $VAR are replaced from the process environment before the YAML is parsed:

database:
  dsn: "postgres://cerbix:${CERBIX_DB_PASSWORD}@127.0.0.1:5432/cerbix?sslmode=disable"
security:
  encryption_key: "${CERBIX_ENCRYPTION_KEY}"

Case	Result
Variable defined	Its value is inserted. Expansion is a single pass; inserted values are not expanded again.
Variable defined but empty	Empty string. This is treated as an explicit choice.
Variable undefined	Startup fails: config: undefined environment variable(s): <names>.
$$	A literal $. Use it for a $ inside a value.

Caution

Expansion runs over the whole file, comments included. The header of config.example.yaml mentions ${ENV_VAR}: if you copy that file unchanged, define ENV_VAR or delete the comment, or startup fails.

Top-level sections

Section	Purpose
server	Listen address, ops endpoint paths, reverse-proxy trust for the login rate limiter.
log	Log level and format.
database	PostgreSQL DSN.
rabbitmq	Broker URL for the distributed roles, and the management API.
oidc	OpenID Connect login (seed; see UI settings).
local	Built-in email and password login.
session	Session cookie.
prober	SSRF policy for probe targets.
notification_egress	SSRF policy for alert delivery (webhooks, Slack, SMTP).
result	Result ingest: clock-skew bound and revision gate mode.
heartbeats	Raw heartbeat retention.
audit	Audit evidence retention and purge cadence.
services	Fan-out caps for Services.
gate	Release gate rate limits and decision-ledger retention.
change	Change intelligence rate limits, clock window and retention.
ledger	Expected-run ledger.
security	Bootstrap admin, at-rest encryption keys, per-region dispatch keyrings.
secrets	Project secret inventory. Off by default.
mail	SMTP for password reset and status-page subscribers (seed).
pull	HTTP-pull transport for geo probers.
providers	Monitoring as code file providers.

Keys operators usually set

Server, logging, storage

Key	Default	Notes
server.listen	:8080	Must not be empty. Serves the UI, the API and the ops endpoints.
server.trusted_proxy_count	0	Reverse-proxy hops in front of cerbix. 0 trusts no X-Forwarded-For. Set it to your real hop count, or every client behind the proxy shares one rate-limit bucket.
server.trusted_proxy_cidrs	empty	Networks of your own proxies. When set, it supersedes trusted_proxy_count.
log.level	info	debug, info, error or critical.
log.format	json	json or text.
database.dsn	empty	Required when local or oidc login is enabled. PostgreSQL 15 or later.
rabbitmq.url	empty	Required for --role api, scheduler and worker.
heartbeats.retention_days	30	Minimum 2. Longer SLA windows read purged days from the daily rollup.
audit.retention_days	365	Range 30–3650.

Login and sessions

Key	Default	Notes
local.enabled	false	Enables email and password login.
local.min_password_length	8	security.admin_password must meet it.
local.login_rate_limit_per_minute	10	Failed sign-in and reset attempts per client IP. 0 disables the limit.
session.ttl	24h	Go duration string. Must be positive.
session.secure	true	Marks the cookie Secure. Set false only for local HTTP development.
session.cookie_name	cerbix_session	Must not be empty.
oidc.issuer	empty	Empty disables OIDC. When set, oidc.client_id, oidc.redirect_url and database.dsn are required. See OIDC.

Security and secrets

Key	Default	Notes
security.admin_email, security.admin_password	empty	Create a global admin on first start when local.enabled is true, both are set and no user exists. The password is never generated or logged.
security.encryption_key	empty	Base64 of 32 bytes (AES-256). Encrypts secrets stored at rest, such as notification-channel credentials and webhook signing secrets. Empty stores them in plaintext. Generate with openssl rand -base64 32.
security.previous_keys	[]	Old keys kept readable during rotation. Run cerbix reencrypt, then remove them.
secrets.enabled	false	Requires secrets.dispatch_envelope: "enforced", security.encryption_key and a security.dispatch keyring.

Danger

Losing security.encryption_key makes every secret encrypted with it unreadable. Back it up outside the database.

Egress, mail, Services

Key	Default	Notes
prober.allow_private_ips	true	Probes may reach RFC 1918, loopback and ULA addresses.
prober.allow_metadata_ips	false	Link-local and cloud metadata addresses stay blocked.
notification_egress.allow_private_ips	false	Set true only if webhooks or SMTP point at internal addresses.
mail.smtp_host, mail.from	empty	Mail is enabled when both are set.
mail.smtp_port	none	Must be positive when mail is enabled. The example file uses 587.
mail.public_base_url	empty	Required when mail is enabled. Builds confirm, unsubscribe and reset links.
services.max_services_per_project	50	Hard maximum 200.
services.max_members_per_revision	50	Hard maximum 200.
services.max_services_per_monitor	10	Hard maximum 25.

The gate, change, ledger, result, pull and providers sections each document their keys and ranges in the example file.

Settings stored in the database

Some settings are edited by a global admin under Settings. The file is only a seed for them:

1. Database. Once a group is saved in the UI, the stored value is authoritative for the whole group, and the file’s keys for that group are ignored.
2. Config file. Until then, the group uses the file’s values where a counterpart exists.
3. Built-in defaults fill the rest.

Group	Settings tab	Seeded from
Single sign-on (OIDC)	Authentication	oidc.*
Login policy	Authentication	local.min_password_length, session.ttl
Email	Email	mail.*
Branding	Branding	none (product name cerbix)
Alerting (global silence)	Alerting	none (off)
Monitor defaults	Monitor defaults	none (interval 60 s, timeout 10 s, retries 0, failure threshold 1)

A saved OIDC override is authoritative even when it disables OIDC; the oidc: block is then ignored. Other replicas reload the remaining groups every 30 s. session.secure, session.cookie_name and local.login_rate_limit_per_minute stay file-only.

Roles

cerbix serve --config <path> --role <role> selects what the process runs. The default is all. --region <name> sets the worker or agent region; empty means core.

Role	Runs	Needs
all	Everything in one process, with an in-process job dispatcher.	PostgreSQL
api	REST API, SSE, UI, result consumer, outbox delivery.	PostgreSQL, RabbitMQ
scheduler	Leader-elected scheduler: due jobs, rollups, retention, alert evaluation, escalations.	PostgreSQL, RabbitMQ
worker	Stateless prober pool.	RabbitMQ
agent	HTTP-pull prober for a region with no broker access.	pull.server_url, pull.token

worker and agent must not hold security.encryption_key or security.previous_keys; startup refuses it. Before starting several roles on a schema with new migrations, run cerbix migrate --config <path> once. See Architecture.

Ops endpoints

Every role serves these on server.listen, without authentication. The paths are set by server.healthz_path, server.readyz_path and server.metrics_path and must start with /.

Path	Answers
/healthz	Liveness. Always 200 with {"status":"ok"} while the process serves HTTP.
/readyz	Readiness. 200 with {"status":"ready"}, or 503 with {"status":"not_ready","error":"<reason>"}.
/metrics	Prometheus text format. cerbix_ready reports the same verdict as /readyz.

Keep /metrics off the public edge. See Metrics and alerts and the runbook.