docker-patterns

name	docker-patterns
description	로컬 개발, 컨테이너 보안, 네트워킹, 볼륨 전략 및 멀티 서비스 오케스트레이션을 위한 Docker 및 Docker Compose 패턴. 컨테이너화된 개발 환경을 설정하거나 Docker 구성을 검토할 때 사용하세요.
metadata	{"origin":"ECC"}

Docker 패턴 (Docker Patterns)

컨테이너화된 개발을 위한 Docker 및 Docker Compose 모범 사례입니다.

활성화 시기

• 로컬 개발을 위해 Docker Compose를 설정할 때
• 멀티 컨테이너 아키텍처를 설계할 때
• 컨테이너 네트워킹 또는 볼륨 문제를 해결할 때
• 보안 및 크기 최적화를 위해 Dockerfile을 검토할 때
• 로컬 개발 환경에서 컨테이너 기반 워크플로우로 전환할 때

로컬 개발을 위한 Docker Compose

표준 웹 앱 스택 (Web App Stack)

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: dev                     # 멀티 스테이지 Dockerfile의 dev 스테이지 사용
    ports:
      - "3000:3000"
    volumes:
      - .:/app                        # 핫 리로드(hot reload)를 위한 바인드 마운트
      - /app/node_modules             # 익명 볼륨 -- 컨테이너 내 의존성 보존
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
      - REDIS_URL=redis://redis:6379/0
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: npm run dev

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

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redisdata:/data

  mailpit:                            # 로컬 이메일 테스트 도구
    image: axllent/mailpit
    ports:
      - "8025:8025"                   # 웹 UI
      - "1025:1025"                   # SMTP

volumes:
  pgdata:
  redisdata:

개발용 vs 프로덕션용 Dockerfile

# 스테이지: 의존성 설치
FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# 스테이지: 개발용 (핫 리로드, 디버그 도구 포함)
FROM node:22-alpine AS dev
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "run", "dev"]

# 스테이지: 빌드
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --production

# 스테이지: 프로덕션용 (최소 크기 이미지)
FROM node:22-alpine AS production
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
USER appuser
COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./
ENV NODE_ENV=production
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/server.js"]

오버라이드(Override) 파일

# docker-compose.override.yml (자동 로드되는 개발 전용 설정)
services:
  app:
    environment:
      - DEBUG=app:*
      - LOG_LEVEL=debug
    ports:
      - "9229:9229"                   # Node.js 디버거 포트

# docker-compose.prod.yml (프로덕션을 위한 명시적 설정)
services:
  app:
    build:
      target: production
    restart: always
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M

# 개발 환경 (자동으로 override 파일 로드)
docker compose up

# 프로덕션 환경
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

네트워킹 (Networking)

서비스 디스커버리 (Service Discovery)

동일한 Compose 네트워크 내의 서비스들은 서비스 이름으로 통신합니다:

# "app" 컨테이너에서 호출 시:
postgres://postgres:postgres@db:5432/app_dev    # "db"가 db 컨테이너로 해석됨
redis://redis:6379/0                             # "redis"가 redis 컨테이너로 해석됨

커스텀 네트워크

services:
  frontend:
    networks:
      - frontend-net

  api:
    networks:
      - frontend-net
      - backend-net

  db:
    networks:
      - backend-net              # api에서만 도달 가능하며 frontend에서는 접근 불가

networks:
  frontend-net:
  backend-net:

필요한 것만 노출하기

services:
  db:
    ports:
      - "127.0.0.1:5432:5432"   # 호스트에서만 접근 가능하며 외부 네트워크에는 비노출
    # 프로덕션에서는 ports 항목을 아예 제외할 수 있음 -- Docker 네트워크 내에서만 통신

볼륨(Volume) 전략

volumes:
  # 이름이 있는 볼륨: 컨테이너 재시작 시에도 데이터가 유지되며 Docker가 관리함
  pgdata:

  # 바인드 마운트: 호스트 디렉토리를 컨테이너에 매핑함 (개발 시 유용)
  # - ./src:/app/src

  # 익명 볼륨: 바인드 마운트 시 컨테이너에서 생성된 콘텐츠를 호스트 폴더가 덮어쓰지 않도록 보호함
  # - /app/node_modules

일반적인 패턴

services:
  app:
    volumes:
      - .:/app                   # 소스 코드 (핫 리로드를 위한 바인드 마운트)
      - /app/node_modules        # 호스트 폴더가 컨테이너의 node_modules를 덮어쓰지 않도록 보호
      - /app/.next               # 빌드 캐시 보호

  db:
    volumes:
      - pgdata:/var/lib/postgresql/data          # 영구 데이터 저장
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql  # 초기화 스크립트

컨테이너 보안

Dockerfile 강화 (Hardening)

# 1. 특정 태그 사용 (절대로 :latest 사용 금지)
FROM node:22.12-alpine3.20

# 2. non-root 사용자로 실행
RUN addgroup -g 1001 -S app && adduser -S app -u 1001
USER app

# 3. 불필요한 기능 제거 (compose에서 설정)
# 4. 가능한 경우 읽기 전용(read-only) 루트 파일 시스템 사용
# 5. 이미지 레이어에 비밀 정보(secrets)를 넣지 않음

Compose 보안

services:
  app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
      - /app/.cache
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE          # 1024 미만 포트에 바인딩할 때만 필요

비밀 정보(Secrets) 관리

# 좋음: 환경 변수 사용 (런타임에 주입)
services:
  app:
    env_file:
      - .env                     # 절대로 .env를 git에 커밋하지 마세요
    environment:
      - API_KEY                  # 호스트 환경에서 상속받음

# 좋음: Docker secrets (Swarm 모드 사용 시)
secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  db:
    secrets:
      - db_password

# 나쁨: 이미지에 하드코딩
# ENV API_KEY=sk-proj-xxxxx      # 절대로 이렇게 하지 마세요

.dockerignore

node_modules
.git
.env
.env.*
dist
coverage
*.log
.next
.cache
docker-compose*.yml
Dockerfile*
README.md
tests/

디버깅

유용한 명령어

# 로그 확인
docker compose logs -f app           # app 로그 팔로우
docker compose logs --tail=50 db     # db의 마지막 50줄 확인

# 실행 중인 컨테이너에서 명령어 실행
docker compose exec app sh           # app 컨테이너 셸 접속
docker compose exec db psql -U postgres  # postgres 접속

# 상태 확인
docker compose ps                     # 실행 중인 서비스 확인
docker compose top                    # 각 컨테이너의 프로세스 확인
docker stats                          # 리소스 사용량 확인

# 재빌드
docker compose up --build             # 이미지 재빌드 후 시작
docker compose build --no-cache app   # 캐시 없이 전체 재빌드

# 정리
docker compose down                   # 컨테이너 중지 및 제거
docker compose down -v                # 볼륨까지 제거 (데이터 삭제 주의!)
docker system prune                   # 미사용 이미지/컨테이너 정리

네트워크 문제 디버깅

# 컨테이너 내부에서 DNS 확인
docker compose exec app nslookup db

# 연결 확인
docker compose exec app wget -qO- http://api:3000/health

# 네트워크 검사
docker network ls
docker network inspect <project>_default

안티 패턴 (Anti-Patterns)

# 나쁨: 오케스트레이션 도구 없이 프로덕션에서 docker compose 사용
# 프로덕션 멀티 컨테이너 워크로드에는 Kubernetes, ECS 또는 Docker Swarm 사용 권장

# 나쁨: 볼륨 없이 컨테이너에 데이터 저장
# 컨테이너는 일회성입니다 -- 볼륨 없이는 재시작 시 모든 데이터가 유실됨

# 나쁨: root 사용자로 실행
# 항상 non-root 사용자를 생성하여 사용하세요

# 나쁨: :latest 태그 사용
# 재현 가능한 빌드를 위해 특정 버전을 명시하세요

# 나쁨: 하나의 거대한 컨테이너에 모든 서비스 포함
# 관심사 분리: 컨테이너당 하나의 프로세스 지향

# 나쁨: docker-compose.yml에 비밀 정보 포함
# .env 파일(git에서 제외)이나 Docker secrets를 사용하세요

이 스킬을 사용하는 시점

• 로컬 개발을 위한 Docker Compose 설정 시
• 멀티 컨테이너 아키텍처 설계 시
• 컨테이너 관련 문제 해결 시
• 보안 강화를 위한 Dockerfile 검토 시
• 컨테이너 모범 사례 구현 시