Docker Compose: Claude Code 활용 가이드

Docker Composeで再現性のある개발 환경を구축する

Docker Composeは複数の컨테이너を定義・관리するツールで、개발 환경の구축を大幅に효율화할 수 있습니다。Claude Code는 サービス구성の설계からDockerfileの최적화まで、인프라구성もスムーズにサポートします。

풀스택개발 환경の구성

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
# ステージ1: 依存関係のインストール
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

# ステージ2: ビルド
FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# ステージ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공식 문서도 확인해 두세요.