| name | docker-dev-environment |
| description | Use when setting up local development services or running the project locally. Establishes the "stateful services in Docker, app runs native" pattern with Postgres, Redis, MinIO, and Mailpit. |
Docker Dev Environment
Announce at start: "I'm using claude-engineer:docker-dev-environment to run services in Docker and the app native."
Iron Law
Only stateful services run in Docker. The app (frontend + backend) runs NATIVELY in its own shell.
Rationale: instant uvicorn --reload / next dev / vite HMR, real debuggers, and CI/toolchain parity -
Docker handles only the painful-to-install backing services.
The baseline services (docker-compose.yml)
- PostgreSQL - primary DB (
localhost:5432).
- Redis - cache, sessions, rate-limit, job broker (
localhost:6379).
- MinIO - S3-compatible object storage (
localhost:9000 API / 9001 console) + a bucket-bootstrap step.
- Mailpit - email capture for signup/reset flows (
localhost:1025 SMTP / 8025 UI).
All with healthchecks and named volumes. The native app connects via localhost URLs in .env.
The dev flow
docker compose up -d (services only).- Backend in shell A:
uv run uvicorn ... (native).
- Frontend in shell B:
pnpm dev / bun dev / vite (native).
Non-negotiables
- Never containerize the app for local dev (the guard hook will remind you).
- Healthchecks on every service; the app waits for healthy services.
- Secrets/connection strings via
.env (git-ignored), documented.
Full detail (the complete compose file, MinIO bucket bootstrap, Mailpit SMTP config, connection settings):
read references/dev-services.md on demand.
Red flags - STOP
docker compose up that builds/starts the app itself for local dev.- Hardcoded service URLs instead of
.env.
- A service with no healthcheck.
