# docker-dev

> Local dev environment with docker-compose — PostgreSQL, Redis, Mailhog, one-command onboarding

- Author: Edison
- Repository: soilmass/vibe-coding-plugin
- Version: 20260130203730
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/soilmass/vibe-coding-plugin
- Web: https://mule.run/skillshub/@@soilmass/vibe-coding-plugin~docker-dev:20260130203730

---

---
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
```yaml
# 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
```json
{
  "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
```bash
# .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
```bash
#!/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
```bash
# 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
```yaml
# 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