- 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
baseEnvSchemaand callsparseEnv(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.