From 87b464aeb3e3d3e4ac482960b5c12984de3d8dc8 Mon Sep 17 00:00:00 2001 From: bisco Date: Fri, 20 Mar 2026 20:00:17 +0100 Subject: [PATCH] docs: record configuration baseline --- docs/ARCHITECTURE.md | 3 + ...-configuration-and-environment-strategy.md | 98 +++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 docs/adr/0004-configuration-and-environment-strategy.md diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9942afe..1707017 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -24,6 +24,7 @@ The current baseline decision is: - `ADR-0001`: runtime and development stack baseline - `ADR-0002`: initial project structure baseline - `ADR-0003`: containerized developer workflow baseline +- `ADR-0004`: configuration and environment strategy baseline The current baseline assumes: - Python 3 @@ -37,6 +38,8 @@ Future scaffolding and implementation work should also follow the initial reposi Future runtime and scaffolding work should also follow the developer workflow defined in `docs/adr/0003-containerized-developer-workflow.md`, including app and PostgreSQL containers as the baseline local services and container-run development commands by default. +Future scaffolding should also follow the configuration strategy defined in `docs/adr/0004-configuration-and-environment-strategy.md`, including environment-variable based configuration, a repository-owned `.env.example`, local-only secrets, and a simple initial Django settings approach unless a later ADR supersedes it. + ## Future Sections Placeholder Future versions of this document may include sections such as: diff --git a/docs/adr/0004-configuration-and-environment-strategy.md b/docs/adr/0004-configuration-and-environment-strategy.md new file mode 100644 index 0000000..60701e4 --- /dev/null +++ b/docs/adr/0004-configuration-and-environment-strategy.md @@ -0,0 +1,98 @@ +# 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