0005. Environment configuration validated with Zod

Design document, published from the repository at docs/adr/0005-environment-configuration.md.

  • Status: Accepted
  • Date: 2026-11-13

Context

Misconfiguration (missing secrets, wrong ports, malformed URLs) is a common cause of outages and of insecure fallbacks.

Decision

  • Configuration comes only from environment variables (12-factor).
  • Each deployable owns a Zod schema extending baseEnvSchema and calls parseEnv(schema, source) once at startup. The source is passed explicitly.
  • On failure, every problem is reported at once; variable names and rules are shown, values never are.
  • Secrets are required fields with no defaults; they are injected by the platform at run time and never committed (.env* is git- and docker-ignored except .env.example).

Consequences

Startup fails immediately and readably when configuration is wrong. Each service declares exactly the variables it needs, which makes deployment manifests reviewable.