Configuration reference

Server and worker processes require PostgreSQL, immutable object storage, hosted signing, and an explicit process role. Local capture and replay use the CLI/runtime.

Core settings

Use the root .env.example as the only configuration template. Copy it to .env at the repository root; supply secrets through a managed secret store in production.

Local authority

Local capture uses StoragePlaneAdapter → WAL → signed segments → verified reconstruction. A durable local workspace must provide DRC_SEGMENT_SIGNING_KEY_PATH. Ephemeral signing keys are test-only.

Linux all-ports capture

To capture supported TCP/UDP packet metadata from an app started by drc run --all-ports, DRC needs a writable cgroup v2 directory where it can create an isolated child group and place the app before it starts. Set DRC_CAPTURE_CGROUP_ROOT to the path of that directory, as provided by your Linux administrator or container runtime. Do not point it at /sys/fs/cgroup itself, and do not change host cgroup permissions to work around a failed check.

The path must be a normal process cgroup, not a threaded cgroup. Some containers expose a cgroup namespace where creating groups appears to work but moving a process into one is blocked; those environments cannot run this capture mode. DRC checks the cgroup type before daemon startup and explains when the supplied path is unsuitable. A successful type check does not guarantee the container allows process migration; the operating system can still reject it at app launch.

Retention moves immutable segments through the tiers the deployment can physically place bytes in. A deployment with only local disk has hot, warm, and cold; a retention policy that asks for a deeper tier completes at the deepest available tier and reports the tier it applied, so a recorded placement always matches where the bytes really are. Setting DRC_STORAGE_ARCHIVE_ROOT to a separate bulk location adds the deepest tier and makes it honorable: archived segments are verified in the archive before their live copy is reclaimed, reads resolve from whichever placement holds them, and deletion removes every placement.

Hosted authority

The API server and worker use hosted authority only: hosted capture uses bounded PostgreSQL receipts as its durable staging area before publishing a verified immutable artifact. Hosted IP/signup/MFA rate limits and login lockouts are also coordinated through PostgreSQL. A hosted process does not silently fall back to local files when a required authority is unavailable. Schema migrations run as a one-shot deployment job with DRC_PROCESS_ROLE=migration and DRC_DATABASE_MIGRATION_URL; API and worker processes must not receive that credential and never apply DDL at startup. The migration command also connects using the runtime URL to confirm both credentials point to the same database/server but use distinct PostgreSQL roles. Runtime startup rejects superuser, table-owner, or BYPASSRLS-capable roles.

For hosted PostgreSQL deployments, provision a dedicated runtime login from a trusted operator shell using DRC_DATABASE_MIGRATION_URL and a fresh random DRC_RUNTIME_DATABASE_PASSWORD (at least 32 characters):

DRC_DATABASE_MIGRATION_URL='postgres://schema-owner:…@db.example/drc?sslmode=require' \\
DRC_RUNTIME_DATABASE_PASSWORD="$(openssl rand -hex 32)" \\
./infra/db/bootstrap-runtime-role.sh

Store that generated password in the secret manager and set DRC_DATABASE_URL/DATABASE_URL to the same database using drc_runtime; do not pass the migration URL to API/worker services. Run the bootstrap with the same role that will own future SQLx migrations so default privileges apply to future tables and sequences. The script refuses to repurpose an existing login. It grants DML across the public schema because current server code uses direct SQL broadly; it does not attempt to infer a narrower table allowlist. Runtime startup also rejects roles that can create roles/databases or create objects in public.

Important: the shipped migrations do not enable RLS or install tenant policies. The runtime-role split removes table-owner and BYPASSRLS privilege paths, but it is not itself row isolation; explicit tenant predicates in application queries remain the current boundary. Do not claim database-enforced tenant RLS until policies and transaction-local tenant context have been implemented and tested, as described in the tenant-isolation audit.

Enterprise identity and observability

Hosted sign-in supports GitHub and Google OAuth when both provider credentials are configured. Register these exact callback URLs with each provider:

• ${DRC_WEB_ORIGIN}/api/v1/auth/oauth/github/callback
• ${DRC_WEB_ORIGIN}/api/v1/auth/oauth/google/callback

GitHub and Google remain visible as first-class sign-in buttons even before configuration, but the server only completes the flow when the matching client ID and secret are present. Team SSO is self-service OIDC: a workspace administrator adds and validates an issuer in Workspace Settings → SSO, then members choose that named connection from the SSO sign-in page. API keys and external identity assertions remain tenant-scoped. An external assertion is accepted only when its canonical payload, signature, issuer, audience, and time window validate; DRC_IDENTITY_ASSERTION_SECRET is a server-side secret and is never returned by the API.

Identity email delivery is provided by the service configured in DRC_IDENTITY_EMAIL_DELIVERY_URL. DRC authenticates to the delivery service with the shared token in DRC_IDENTITY_EMAIL_DELIVERY_TOKEN (or DRC_IDENTITY_EMAIL_TOKEN), sent as the x-drc-email-token header; the value must match the DRC_IDENTITY_EMAIL_TOKEN configured on the delivery endpoint. DRC sends a JSON request for each verification, password-reset, and workspace-invitation message. The request includes kind, to, email, subject, text, html, action_url, token, and expires_at; the delivery service should send the supplied html or text content without logging the token. Verification links use ${DRC_WEB_ORIGIN}/email-verification/complete?token=..., password reset links use ${DRC_WEB_ORIGIN}/password-reset/complete?token=..., and invitation links use ${DRC_WEB_ORIGIN}/invitations/accept?token=.... Tokens are stored only as SHA-256 hashes, expire after 60 minutes for verification, 30 minutes for password reset, or 7 days for invitations, and are single-use. Set DRC_WEB_ORIGIN to the public browser origin so links resolve to the deployed app. The delivery endpoint should return any 2xx response after accepting the message; non-2xx responses fail the request so the caller can retry.

Use Prometheus, Grafana, Datadog, and OpenTelemetry integrations through the deployment's approved observability boundary. Istio and Linkerd service-mesh deployments must keep mTLS enabled at exposed service boundaries.

Security settings

• Set TLS requirements explicitly and validate certificates before accepting traffic.
• Keep signing, encryption, database, object-store, and provider credentials separate.

Boolean values

Use true or false in configuration. Components normalize case but do not treat an unset security setting as an opt-in production fallback.