# 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