dbis_core/docs/adr/0003-environment-validation.md

ADR-0003: Environment Variable Validation at Startup

Status

Accepted

Context

The application was using environment variables without validation, leading to:

• Runtime errors when required variables were missing
• Security risks from weak or missing secrets
• Difficult debugging when misconfigured
• No clear error messages for configuration issues

Decision

Implement environment variable validation that:

• Runs at application startup
• Validates all required variables
• Provides clear error messages
• Supports different validation rules per environment
• Fails fast if critical variables are missing or invalid

Consequences

Positive

• Early detection of configuration errors
• Clear error messages guide developers
• Prevents runtime failures from misconfiguration
• Security improvements (validates JWT secret strength, CORS config)
• Better developer experience

Negative

• Application won't start if validation fails (by design)
• Requires maintaining validation schema
• Additional startup time (minimal)

Risks

• Breaking changes if validation rules are too strict
• Need to keep validation in sync with actual usage

Alternatives Considered

1. Runtime Validation: Validate when variables are used

   • Pros: More flexible
   • Cons: Errors discovered late, harder to debug

2. Configuration File: Use config file instead of env vars

   • Pros: Type-safe, validated
   • Cons: Doesn't work well with 12-factor app principles

3. Startup Validation: Chosen approach

   • Pros: Fail fast, clear errors, secure defaults
   • Cons: None significant

Implementation

• Created src/shared/config/env-validator.ts
• Integrated into src/index.ts startup
• Validates: DATABASE_URL, JWT_SECRET, ALLOWED_ORIGINS, etc.

References

• 12-Factor App: https://12factor.net/config
• Node.js Environment Variables: https://nodejs.org/en/learn/command-line/how-to-read-environment-variables-from-nodejs