Docker

Local stack: PostgreSQL + Django API, orchestrated by a single docker-compose.yml at the repo root. The API image is built from backend/Dockerfile and boots via backend/entrypoint.sh.

[!info] Authority Stack versions and rationale live in [[adr-002-dev-stack|ADR-002]] / [[adr-002-a-backend-dev-stack|ADR-002-a]]. Environment variables live in [[adr-006-environment-variables|ADR-006]]. This page is operational only.

Services

Service	Container	Image	Port (host → container)
`db`	`kdx-ng-db`	`postgres:16-alpine`	`127.0.0.1:5432 → 5432`
`api`	`kdx-ng-backend-pod`	built from `backend/Dockerfile`	`8000 → 8000`

api depends on db being healthy. Both have healthchecks; api’s probe hits GET /api/health/.

Volumes

Volume / mount	Purpose
`pg_data` (named)	PostgreSQL data. Wiped by `down -v`.
`./backend:/app` (bind)	Live source for hot-reload. Shadows the image’s copied code.
`/app/.venv` (anonymous)	Keeps the container’s venv from being clobbered by the bind mount.
`./API.md:/API.md:ro`	Contract file for the test suite ([[adr-005-a-contract-testing-pipeline

[!note] Fixtures survive down -v Mock fixtures live under ./backend/fixtures/ and are part of the ./backend:/app bind mount, so they are not removed by down -v (which only drops the pg_data volume). See [[mock-data|Mock Data]].

Boot sequence

entrypoint.sh runs on every container start (6 steps):

makemigrations + migrate
create_superuser (skipped if SUPERUSER_PASSWORD is unset) — see [[admin|Admin]]
Local only: loaddata fixtures/mock_clinic.yaml then fixtures/mock_employees.yaml — see [[mock-data|Mock Data]]
collectstatic
flushexpiredtokens
Start server — uvicorn --reload (local) or the production CMD

Steps 2 and 3 are idempotent across restarts (PK-keyed superuser get_or_create and fixture upsert).

Common commands

docker compose up -d                       # start (build on first run)
docker compose up -d --build               # rebuild the api image
docker compose down                        # stop, keep data
docker compose down -v                     # stop, WIPE the database
docker compose logs -f api                 # follow API logs
docker compose exec api python manage.py shell   # Django shell
docker compose exec api pytest             # run the test suite
curl http://localhost:8000/api/health/     # health check