name: docker-dev
description: >
Local dev environment with docker-compose — PostgreSQL, Redis, Mailhog, one-command onboarding
allowed-tools: Read, Grep, Glob

Docker Dev

Purpose

Standardized local development environment using docker-compose. Ensures every developer
runs identical PostgreSQL, Redis, and Mailhog services. One-command onboarding with
npm run setup.

When to Use

• Setting up local development environment for a team
• Adding PostgreSQL, Redis, or mail testing services
• Creating one-command project onboarding scripts
• Ensuring dev/prod environment parity

When NOT to Use

• Production Docker builds → deploy
• CI/CD pipeline configuration → deploy
• Database schema management → prisma
• Cloud infrastructure → deploy

Pattern

docker-compose.yml

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  mailhog:
    image: mailhog/mailhog:latest
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

  # Test database (isolated)
  postgres-test:
    image: postgres:16-alpine
    ports:
      - "5433:5432"
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: app_test
    profiles:
      - test

volumes:
  pgdata:

Package.json scripts

{
  "scripts": {
    "docker:up": "docker compose up -d",
    "docker:down": "docker compose down",
    "docker:reset": "docker compose down -v && docker compose up -d",
    "docker:test": "docker compose --profile test up -d postgres-test",
    "setup": "docker compose up -d && npm install && npx prisma migrate dev && npx prisma db seed",
    "dev": "next dev --turbopack"
  }
}

.env.local template

# .env.local (generated by npm run setup)
DATABASE_URL="postgresql://dev:dev@localhost:5432/app"
UPSTASH_REDIS_REST_URL="http://localhost:6379"
RESEND_API_KEY="re_dev_mailhog"
SMTP_HOST="localhost"
SMTP_PORT="1025"

One-command onboarding script

#!/usr/bin/env bash
# scripts/setup.sh
set -e

echo "Starting services..."
docker compose up -d

echo "Waiting for PostgreSQL..."
until docker compose exec -T postgres pg_isready -U dev; do
  sleep 1
done

echo "Installing dependencies..."
npm install

echo "Running migrations..."
npx prisma migrate dev

echo "Seeding database..."
npx prisma db seed

echo "Setup complete! Run 'npm run dev' to start."

Dev vs test profiles

# Start dev services only
docker compose up -d

# Start dev + test database
docker compose --profile test up -d

# Run tests against isolated DB
DATABASE_URL="postgresql://test:test@localhost:5433/app_test" npx vitest

Hot reload configuration

# Next.js watches src/ — no Docker rebuild needed
# Prisma watches schema — run 'prisma generate' after changes
# Only rebuild Docker if compose file changes

Anti-pattern

Running databases natively

Don't install PostgreSQL or Redis directly on your machine. Docker ensures identical
versions across the team and makes cleanup trivial with docker compose down -v.

Different versions in dev vs prod

Pin exact versions in compose (postgres:16-alpine, not postgres:latest).
Match the version running in production to avoid compatibility surprises.

No health checks

Without health checks, dependent services may start before the database is ready.
Always include healthcheck blocks so depends_on works correctly.

Common Mistakes

• Forgetting volume mounts — data lost on container restart
• Not using --profile test — test DB runs unnecessarily in dev
• Port conflicts with native PostgreSQL — check port 5432 is free
• Missing healthcheck — services start before ready
• Not pinning image versions — latest introduces surprise upgrades

Checklist

• [ ] docker-compose.yml with PostgreSQL, Redis, and mail service
• [ ] All services have health checks
• [ ] npm run setup handles full onboarding
• [ ] npm run docker:up / docker:down scripts exist
• [ ] Test database uses separate profile and port
• [ ] Image versions pinned (not latest)
• [ ] .env.local template provided

Composes With

• scaffold — initial project setup includes Docker
• prisma — migrations run against Docker PostgreSQL
• deploy — Docker build for production deployment
• testing — isolated test database via profiles
• email — Mailhog for local email testing