97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# ADR-0003: Containerized Developer Workflow
|
|
|
|
- Status: accepted
|
|
- Date: 2026-03-20
|
|
|
|
## Context
|
|
|
|
The project has already accepted these baseline decisions:
|
|
- Python 3
|
|
- Django
|
|
- PostgreSQL
|
|
- containerized development by default
|
|
- a single application repository with application code under `app/` and infrastructure assets under `infra/`
|
|
|
|
Before implementation starts, the repository needs one explicit developer-workflow decision so future tasks do not guess how local commands, services, or persistence should work. The workflow must be portable across machines, low-ambiguity, and small enough for the current phase.
|
|
|
|
## Decision
|
|
|
|
Use a Docker Compose style workflow, or an equivalent container orchestration approach with the same behavior, as the baseline developer workflow.
|
|
|
|
The baseline developer workflow must include at least:
|
|
- one application container for Django development work
|
|
- one PostgreSQL container for the baseline database service
|
|
|
|
The baseline workflow also assumes:
|
|
- application source code is mounted into the app container during development
|
|
- routine development commands run through containers by default
|
|
- persistent local development database data is handled through a container-managed persistent volume or equivalent durable container storage
|
|
- host-installed Python is optional and unsupported for normal development workflow
|
|
|
|
Minimum required developer experience:
|
|
- a contributor can start the baseline services through the containerized workflow
|
|
- application commands run inside the app container
|
|
- the application talks to PostgreSQL through the containerized environment
|
|
- the workflow behaves consistently across machines without depending on undocumented local Python setup
|
|
|
|
Future implementation tasks should treat this as direct workflow guidance, not as an optional convenience.
|
|
|
|
## Alternatives Considered
|
|
|
|
### Option A: Docker Compose style baseline with one app container, one PostgreSQL container, mounted source, and container-run commands
|
|
|
|
Chosen.
|
|
|
|
This is the best fit for the current phase because it gives the project one clear, repeatable development path while keeping the service set intentionally small.
|
|
|
|
### Option B: Containerized database, but application commands run on the host machine
|
|
|
|
Not chosen. This would keep too much variation in local Python setup and weaken the portability goal of mandatory containerized development.
|
|
|
|
### Option C: Fully local host-based development with optional containers
|
|
|
|
Not chosen. This conflicts with the already accepted runtime baseline and would reintroduce machine-specific ambiguity.
|
|
|
|
### Option D: More production-like multi-service developer orchestration from the start
|
|
|
|
Not chosen. This would add complexity the project has not yet earned and is not required for the current phase.
|
|
|
|
## Trade-Offs
|
|
|
|
- this workflow adds container orchestration overhead compared with purely local commands
|
|
- mounted source inside the app container improves iteration speed, but requires clear volume and command conventions later
|
|
- persistent database data in container-managed storage is more realistic than ephemeral local-only setup, but requires explicit reset/cleanup decisions later
|
|
|
|
Why this is the best fit for the current phase:
|
|
- it matches the already accepted requirement for containerized development
|
|
- it keeps the developer baseline limited to the minimum useful services
|
|
- it improves portability across machines by standardizing how development commands run
|
|
- it avoids premature production-grade complexity
|
|
|
|
What is intentionally deferred:
|
|
- exact Compose file names or orchestration command names
|
|
- exact image build details
|
|
- reverse proxy or extra service containers
|
|
- production deployment orchestration
|
|
- detailed data reset and backup workflows for local development
|
|
|
|
## Consequences
|
|
|
|
Future implementation tasks should assume:
|
|
- local development commands run through containers by default
|
|
- the app service and PostgreSQL service both exist in the developer baseline
|
|
- source code is mounted into the app container during development
|
|
- database persistence is handled by container-managed durable local storage
|
|
- host-installed Python should not be the normal path for project development
|
|
|
|
Future runtime and scaffolding work should follow this workflow unless a later ADR supersedes it.
|
|
|
|
## Follow-Up Decisions Needed
|
|
|
|
The following decisions are still expected later:
|
|
- exact orchestration file names and locations under `infra/`
|
|
- exact command entrypoints for common development tasks
|
|
- environment variable and secrets handling for the containerized workflow
|
|
- local data reset and cleanup conventions
|
|
- whether any additional developer services are needed beyond app and PostgreSQL
|