hoopscout-v2/docs/adr/0004-configuration-and-environment-strategy.md

ADR-0004: Configuration and Environment Strategy

• Status: accepted
• Date: 2026-03-20

Context

The project has already accepted these baseline decisions:

• Python 3
• Django
• PostgreSQL
• containerized development by default
• a Docker Compose style developer workflow

Before implementation starts, the repository needs one explicit configuration strategy so future prompts do not guess how environment-specific values, secrets, or Django settings should be handled.

The baseline must stay simple, portable, and easy to understand across machines. It should work cleanly with containerized development without introducing a complex configuration framework before the application exists.

Decision

Use environment variables as the baseline mechanism for runtime and application configuration.

The baseline strategy is:

• keep a versioned .env.example file in the repository
• never commit real secrets, local-only credentials, or machine-specific private values
• use local-only env files or equivalent local secret sources for actual sensitive values
• have container orchestration provide environment variables through env files, direct environment variable definitions, or both
• keep the initial Django configuration readable with one baseline settings module rather than a split-settings package by default

Future implementation prompts should assume:

• application/runtime configuration enters the app container through environment variables
• .env.example documents the expected variable names and non-secret examples
• local-only secrets stay out of git
• container orchestration is responsible for wiring config into containers
• Django settings should remain understandable and maintainable before any more advanced settings split is justified

Alternatives Considered

Option A: Environment-variable baseline with a committed .env.example, local-only secret files, and a simple initial Django settings module

Chosen.

This is the best fit for the current phase because it is portable, familiar, and easy to document without adding unnecessary configuration layers.

Option B: Commit more concrete local config files with real environment-specific values

Not chosen. This would create unnecessary risk and conflict with the requirement that secrets and machine-specific values stay local.

Option C: Adopt a more elaborate split-settings or multi-layer configuration framework immediately

Not chosen. This would add complexity before the project has enough implementation pressure to justify it.

Option D: Rely primarily on host-local configuration outside the container workflow

Not chosen. This would weaken the clarity and portability of the mandatory containerized development baseline.

Trade-Offs

• environment variables keep the baseline simple, but they require careful documentation of expected names and meanings
• using .env.example improves onboarding clarity, but future work must ensure example values stay non-sensitive
• keeping one initial Django settings module is easier to understand early on, but future settings growth may eventually justify a more structured split

What is expected to live in git:

• .env.example
• documented variable names and non-secret defaults/examples
• configuration documentation
• application settings code that reads from environment variables

What must stay local:

• real secrets
• real local credentials
• developer-specific overrides that should not be shared
• machine-specific private paths or values

How developers should expect configuration to enter containers:

• through the container orchestration layer
• using env files, direct environment variable definitions, or both
• without requiring host-installed Python configuration as the normal workflow

Consequences

Future implementation tasks should:

• define configuration through environment variables
• add a repository-owned .env.example
• keep real secrets out of git
• wire application containers to read configuration from container-supplied environment variables
• keep the first Django settings layout simple and understandable

Future scaffolding should follow this configuration strategy unless a later ADR supersedes it.

Follow-Up Decisions Needed

The following decisions are still expected later:

• exact initial variable names and documented defaults
• exact env file names and placement for local development
• whether any non-secret shared defaults should live in orchestration files directly
• whether and when Django settings should be split into multiple modules
• how production and non-development secret delivery will work later