Carlos Oliva Pascual

Posted on Jul 9 • Originally published at stacknotice.com

Docker Compose for Local Development: Complete Setup (2026)

#docker #nextjs #postgres #devops

git clone → make dev → working environment with Postgres, Redis, and email testing, same for every developer. That's the goal.

The docker-compose.yml

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules  # use container's node_modules, not host's
      - /app/.next
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
      - REDIS_URL=redis://cache:6379
      - SMTP_HOST=mailhog
      - SMTP_PORT=1025
    env_file:
      - .env.local
    depends_on:
      db:
        condition: service_healthy  # wait for Postgres to actually be ready

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
      interval: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes

  mailhog:
    image: mailhog/mailhog:latest
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI — view emails at localhost:8025

volumes:
  postgres_data:
  redis_data:

Services communicate by service name: db:5432, cache:6379, mailhog:1025.

Dev Dockerfile with Hot Reload

# Dockerfile.dev
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
EXPOSE 3000
CMD ["npm", "run", "dev"]

Source code is mounted via volume — no COPY . needed. Changes on the host are immediately visible inside the container. node_modules from npm ci runs inside the container, the host's version is excluded.

.env Setup

# .env.example (committed — template)
DATABASE_URL=postgresql://postgres:postgres@db:5432/myapp
REDIS_URL=redis://cache:6379
SMTP_HOST=mailhog
SMTP_PORT=1025
NEXTAUTH_SECRET=

# .env.local (not committed — real secrets)
NEXTAUTH_SECRET=generate-a-real-secret
STRIPE_SECRET_KEY=sk_test_...

The Makefile

.PHONY: dev down reset db-migrate db-seed shell psql logs

dev:
    docker compose up --build

dev-bg:
    docker compose up --build -d

down:
    docker compose down

reset:
    docker compose down -v && docker compose up --build

db-migrate:
    docker compose exec app npm run db:migrate

db-seed:
    docker compose exec app npm run db:seed

db-reset:
    docker compose exec db psql -U postgres -c "DROP DATABASE IF EXISTS myapp;"
    docker compose exec db psql -U postgres -c "CREATE DATABASE myapp;"
    $(MAKE) db-migrate db-seed

shell:
    docker compose exec app sh

psql:
    docker compose exec db psql -U postgres -d myapp

logs:
    docker compose logs -f

logs-%:
    docker compose logs -f $*

add:
    docker compose exec app npm install $(pkg) && docker compose restart app

status:
    docker compose ps

Performance on Mac

node_modules on a host-mounted volume is slow on macOS. Use named volumes instead:

volumes:
  - .:/app
  - node_modules:/app/node_modules   # named volume — lives in the Linux VM
  - next_cache:/app/.next

volumes:
  node_modules:
  next_cache:
  postgres_data:
  redis_data:

Named volumes never cross the VM boundary — npm install and Next.js builds are dramatically faster.

Also enable VirtioFS in Docker Desktop: Settings → General → Use VirtioFS (macOS Ventura+).

Health Checks

db:
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
    interval: 5s
    timeout: 5s
    retries: 5

app:
  depends_on:
    db:
      condition: service_healthy  # app waits until Postgres accepts connections

Without this, Next.js tries to connect to Postgres before it's initialized, crashes, and you wonder why.

CI/CD with the Same Stack

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start services
        run: docker compose up -d db cache

      - name: Wait for Postgres
        run: until docker compose exec -T db pg_isready -U postgres; do sleep 1; done

      - run: npm ci
      - run: npm run db:migrate
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/myapp
      - run: npm test
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/myapp
          REDIS_URL: redis://localhost:6379

App runs directly in CI (faster), but uses the same Docker images for Postgres and Redis.

New Developer Onboarding

git clone https://github.com/org/myapp && cd myapp
cp .env.example .env.local
# Fill in any real API keys

make dev        # starts everything
make db-migrate # in another terminal
make db-seed

open http://localhost:3000  # app
open http://localhost:8025  # emails (MailHog UI)

MailHog catches all outgoing emails — registration, password reset, notifications — without real SMTP or accidentally emailing users.

.dockerignore

node_modules
.next
.git
.env*.local
*.log
coverage

Full article at stacknotice.com/blog/docker-compose-local-dev-2026

DEV Community