ADR-0002: Docker Compose for Local Developer Environment¶
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2026-06-16 |
| Deciders | Arun Singh |
Context¶
New engineer onboarding was taking hours — installing .NET, PostgreSQL, setting PATH variables, running migrations, seeding data, starting services. Each step had environment-specific failure modes. There was no reproducible setup.
The team needed a zero-friction local setup that: - Works on macOS, Linux, and Windows (via Docker) - Is idempotent and safe to re-run - Mirrors production topology - Has smoke tests to verify the stack is healthy
Decision¶
Provide two paths, both fully scripted:
- Docker Compose — zero local dependencies; three services in one command
- macOS one-command script (
scripts/dev-setup-macos.sh) — native performance; idempotent; 10-step setup with smoke tests
Additionally provide a VS Code DevContainer for fully isolated reproducibility.
All three paths converge on the same smoke test suite (scripts/smoke-test.sh, 10 assertions).
Rationale¶
| Option | Why rejected / accepted |
|---|---|
| Manual setup docs only | Docs drift; every machine has different failure modes |
| Docker-only | Native .NET performance matters for the scanner hot-path during development; dotnet watch and F5 debugging work better native |
| Nix/devenv | Too complex for the current team size; unfamiliar toolchain |
| Docker Compose + native script (chosen) | Covers all developer preferences; Docker path works for CI; native path works for fast iteration |
Consequences¶
Becomes easier: - New engineer productive in < 30 minutes - CI uses the same Docker Compose stack as local dev - Environment parity: same migrations, same seed data, same smoke tests in all environments
Becomes harder: - Two paths to maintain (Docker and native scripts) - Database password is in scripts — must move to secrets manager before production use (credential stored in shared password manager, not in docs)