ADR 0010: Environment Profiles and Config Governance

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: Twelve-factor style apps read config from the environment so the same build can run in dev, staging, and prod. If profiles are fuzzy, teams accidentally ship debug logging, mock auth, or open CORS to production—often discovered by incident, not review.

We need explicit profiles (dev, qa, prod), one documented template, and validation that rejects unsafe combinations in non-dev environments.

Decision

• Adopt explicit environment profiles: dev, qa, prod only.
• Single committed template: env/example (copy to .env via make env-init).
• Load configuration in layers: .env -> env/<APP_ENV> -> optional ENV_FILE.
• Automated tests use APP_ENV=qa (not a separate profile). Legacy APP_ENV=test maps to qa.
• Normalize legacy aliases (for example local -> dev).
• Expose effective profile in GET /live as app_env.
• Enforce strict runtime validation for unsafe settings in qa/prod.

Validation Rules

• qa/prod: API_AUTH_STRATEGY=disabled is forbidden.
• qa/prod: default API_MOCK_API_KEY is forbidden.
• qa/prod: METRICS_ENABLED must be true.
• prod: localhost origins in CORS are forbidden.
• prod: LOG_LEVEL=DEBUG is forbidden.

Implementation

• Profile-aware loader and validation are implemented in app/core/config.py.
• Directory env/ holds example plus small overrides dev, qa, prod.
• Observability compose stack is env-driven for ports, scrape target, and Grafana credentials.

Consequences

Positive

• Clear branch logic for environment behavior with safer defaults.
• Reduced risk of accidental insecure production configuration.
• Better developer onboarding for environment-specific setup.

Trade-offs

• More env variables and templates to maintain.
• Startup can fail fast when policy validations detect invalid runtime config.

Page history