# Docker Dev Environment

> 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.

- Skill: `martian56/docker-dev-environment` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add martian56/docker-dev-environment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/martian56/docker-dev-environment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: martian56 (https://skillmd.com/u/martian56)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/martian56/docker-dev-environment

---


# 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
1. `docker compose up -d` (services only).
2. Backend in shell A: `uv run uvicorn ...` (native).
3. Frontend in shell B: `pnpm dev` / `bun dev` / `vite` (native).

## Non-negotiables
1. Never containerize the app for local dev (the guard hook will remind you).
2. Healthchecks on every service; the app waits for healthy services.
3. 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.