Docker Compose with Claude Code

Building Reproducible Dev Environments With Docker Compose

Docker Compose is a tool for defining and managing multiple containers, and it can dramatically streamline dev environment setup. Claude Code smoothly supports infrastructure configuration as well, from designing the service topology to optimizing your Dockerfile.

A Full-Stack Dev Environment

Ask Claude Code to design the overall project structure.

> Build a Docker Compose dev environment with Next.js + PostgreSQL + Redis.
> Include hot reload support, initial data seeding, and health checks.

# docker-compose.yml
version: "3.9"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run dev

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

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

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"
      - "8025:8025"

volumes:
  postgres_data:
  redis_data:

Optimizing the Development Dockerfile

A dev Dockerfile that supports hot reload.

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

# Copy package files first so we can leverage the build cache
COPY package.json package-lock.json ./
RUN npm ci

# Source code is shared via a volume mount
# (no COPY needed - configured in docker-compose.yml)

EXPOSE 3000

CMD ["npm", "run", "dev"]

A Multi-Stage Build for Production

An optimized Dockerfile for production deployments.

# Dockerfile
# Stage 1: install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# Stage 2: build
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Stage 3: production image
FROM node:20-alpine AS runner
WORKDIR /app

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]

Separating Configs by Environment

A pattern that keeps development, test, and production config separate.

# docker-compose.override.yml (loaded automatically in dev)
services:
  app:
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - DEBUG=true
      - LOG_LEVEL=debug

  db:
    ports:
      - "5432:5432"

  adminer:
    image: adminer
    ports:
      - "8080:8080"
    depends_on:
      - db

# docker-compose.test.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp_test
      - NODE_ENV=test
    command: npm run test:ci
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp_test
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    tmpfs:
      - /var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 3s
      retries: 10

Simplifying Commands With a Makefile

Collect common commands in a Makefile.

.PHONY: up down build logs db-shell db-migrate db-seed test

up:
	docker compose up -d

down:
	docker compose down

build:
	docker compose build --no-cache

logs:
	docker compose logs -f app

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

db-migrate:
	docker compose exec app npx prisma migrate dev

db-seed:
	docker compose exec app npx prisma db seed

test:
	docker compose -f docker-compose.yml -f docker-compose.test.yml run --rm app

clean:
	docker compose down -v --remove-orphans

Summary

With Docker Compose, everyone on the team can easily reproduce the same development environment. With Claude Code, you can efficiently build service topology, optimized Dockerfiles, environment separation, and more.

For deeper container-based dev environment integration, see the Dev Container configuration guide, and for CI/CD pipeline integration, see the CI/CD setup guide. You should also check the official Docker Compose documentation.