Docker Compose 실전: Claude Code로 개발 환경 구축하기

Docker Compose로 재현 가능한 개발 환경 구축하기

Docker Compose는 여러 컨테이너를 정의하고 관리하는 도구로, 개발 환경 구축을 크게 효율화해 줍니다. 서비스 구성 설계부터 Dockerfile 최적화까지 Claude Code가 인프라 구성을 원활하게 도와줍니다.

풀스택 개발 환경 구성

Claude Code에 프로젝트 전체 구성을 맡겨 봅시다.

> Next.js + PostgreSQL + Redis 개발 환경을
> Docker Compose로 구축해줘.
> 핫 리로드, 초기 데이터 투입, 헬스 체크까지 포함해서.

# 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:

개발용 Dockerfile 최적화

핫 리로드에 대응한 개발용 Dockerfile입니다.

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

# 패키지 파일만 먼저 복사해서 캐시 활용
COPY package.json package-lock.json ./
RUN npm ci

# 소스 코드는 볼륨 마운트로 공유
# COPY는 불필요 (docker-compose.yml에서 설정)

EXPOSE 3000

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

프로덕션용 멀티스테이지 빌드

프로덕션 배포용 최적화 Dockerfile입니다.

# Dockerfile
# Stage 1: 의존성 설치
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

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

# Stage 3: 프로덕션 이미지
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"]

환경별 설정 파일 분리

개발/테스트/프로덕션에서 설정을 분리하는 패턴입니다.

# docker-compose.override.yml (개발 환경용, 자동 로드)
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

Makefile로 명령어 단순화

자주 쓰는 명령어를 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

정리

Docker Compose를 쓰면 팀원 모두가 동일한 개발 환경을 손쉽게 재현할 수 있습니다. Claude Code를 활용하면 서비스 구성, Dockerfile 최적화, 환경 분리 같은 인프라 설정을 효율적으로 구축할 수 있죠.

컨테이너 기반 개발 환경의 추가 통합은 Dev Container 설정 가이드에서, CI/CD 파이프라인과의 연동은 CI/CD 셋업 가이드에서 다룹니다. Docker Compose 공식 문서도 함께 확인해 보세요.