阅读中文版本

Set Up Local Development with Docker Compose

Configure a docker-compose.yml file to run your application, database, and cache services together with hot-reload for development, ensuring consistent environments across team members.

Why Docker Compose for Development

Docker Compose ensures every developer (and CI) uses identical database versions, Redis configurations, and environment variables. No more “works on my machine” issues.

Complete docker-compose.yml

services:
  app:
    build:
      context: .
      target: development
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://dev:devpass@postgres:5432/myapp
      REDIS_URL: redis://redis:6379
      NODE_ENV: development
    volumes:
      - .:/app                      # hot-reload: mirror host code into container
      - node_modules:/app/node_modules  # named volume prevents host overwrite
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: pnpm dev               # your dev server command

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev -d myapp"]
      interval: 5s
      timeout: 5s
      retries: 5

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

volumes:
  pgdata:
  redisdata:
  node_modules:

Key Patterns

named volume for node_modules

Without the named volume, Docker bind-mounts the host directory /app which includes node_modules. On macOS/Windows, the host has no node_modules → the container’s compiled modules get overwritten → native addons break.

Healthchecks vs depends_on

Without healthchecks, app starts immediately when postgres container is created (not when ready):

# ❌ Starts app when container created, not when postgres accepts connections
depends_on: [postgres]

# ✅ Waits until pg_isready succeeds
depends_on:
  postgres:
    condition: service_healthy

Hot-Reload with Bind Mount

The bind mount .:/app syncs host → container. Your dev server (vite, tsx watch, nodemon) detects changes instantly.

Common Commands

# Start all services in background
docker compose up -d

# View logs for a specific service
docker compose logs -f app

# Run a one-off command (e.g., migrations)
docker compose exec app pnpm migrate

# Stop everything and remove volumes
docker compose down -v

# Rebuild only the app container after Dockerfile change
docker compose build app

Multi-Stage Dockerfile Reference

FROM node:20-alpine AS development
WORKDIR /app
COPY package*.json ./
RUN pnpm install
COPY . .
CMD ["pnpm", "dev"]

FROM development AS production
RUN pnpm prune --prod
RUN pnpm build
CMD ["node", "dist/server.js"]

Troubleshooting