Docker Compose AI 최적화 가이드

핵심 기능 및 사용 목적

Docker Compose v2.39.3: 여러 컨테이너를 YAML 파일로 통합 관리하는 도구

• 주요 이점: docker run 명령어 반복 제거, 포트/네트워크 설정 자동화
• 대상 환경: 개발/테스트 환경 (프로덕션 부적합)

핵심 구성 요소

기본 설정 구조

services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: password

환경변수 관리 (보안 필수)

# .env 파일 사용 (Git 제외 필수)
environment:
  POSTGRES_USER: ${DB_USER}
  POSTGRES_PASSWORD: ${DB_PASSWORD}

치명적 실패 시나리오

1. depends_on 오해 (높은 빈도)

문제: depends_on은 컨테이너 시작만 보장, 서비스 준비 상태 미보장
결과: 웹앱이 DB 초기화 완료 전 연결 시도 → 연결 실패
해결책: healthcheck 필수 사용

db:
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    retries: 5

2. 메모리 부족 (OOM Killer)

증상: 컨테이너 갑작스런 종료 (Exit code 137)
원인: 기본 메모리 제한 부족 (Node.js 앱 512M 부족)
해결책: 리소스 제한 명시적 설정

deploy:
  resources:
    limits:
      memory: 1G

3. M1/M2 Mac 성능 저하

문제: x86 이미지 에뮬레이션으로 인한 극심한 성능 저하
영향: PostgreSQL 시작 시간 30초 초과
해결책: ARM 네이티브 이미지 사용

• postgres:15-alpine (ARM 지원)
• Dockerfile에 FROM --platform=linux/arm64/v8 명시

성능 및 리소스 요구사항

메모리 사용량

• 기본 설정: 과도한 메모리 소비
• M1/M2 Mac: x86 에뮬레이션으로 인한 추가 오버헤드
• 권장 설정: 명시적 메모리 제한 필수

파일 동기화 성능

• 볼륨 마운트: 특히 node_modules 폴더에서 극심한 지연
• 코드 변경 반영: 5초 이상 지연 발생
• 완화 방법:
  • VirtioFS 활성화 (Docker Desktop)
  • Mutagen 동기화 도구 사용
  • Watch 모드 활용 (v2.22+)

프로덕션 배포 제약사항

사용 금지 이유

• 단일 장애점: 서버 하나 장애 시 전체 서비스 중단
• 무중단 배포 불가: 배포 중 서비스 중단 불가피
• 모니터링/로깅 부족: 운영 관찰성 기능 미비
• 자동 복구 없음: 장애 발생 시 수동 개입 필요

대안 솔루션

• Kubernetes: 복잡하지만 프로덕션 필수 기능 제공
• AWS ECS: 관리형 컨테이너 오케스트레이션
• Docker Swarm: 경량 클러스터링 (제한적 기능)

일반적 오류 및 해결책

네트워크 관련

• "network not found": docker compose down 후 재시작
• 포트 충돌: lsof -i :포트번호로 점유 프로세스 확인
• 컨테이너 간 통신 실패: IP 대신 서비스명 사용 필수

데이터 영속성

• 데이터 손실: named volume 사용 (바인드 마운트 권한 문제 주의)

volumes:
  - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

디스크 공간

• "no space left on device": docker system prune -a로 정리 (5분 소요, 수 GB 회복)

버전별 주요 기능

v2.22+ Watch 모드

develop:
  watch:
    - action: sync
      path: ./src
      target: /app/src
    - action: rebuild
      path: ./package.json

제한사항: Node.js node_modules 여전히 느림

도구 비교 매트릭스

도구	복잡도	성능	프로덕션 적합성	학습 곡선
Docker Compose	낮음	보통	부적합	쉬움
Kubernetes	매우 높음	높음	적합	매우 어려움
Podman Compose	낮음	높음	제한적	쉬움
AWS ECS	중간	높음	적합	보통

운영 지침

보안 고려사항

• .env 파일 Git 제외 필수
• 환경변수 하드코딩 금지
• GitLeaks 도구로 사전 검증

모니터링 필수 지표

• 메모리 사용량: docker stats
• 컨테이너 상태: 재시작 빈도 추적
• 로그 크기: 제한 설정 필요

logging:
  options:
    max-size: "10m"
    max-file: "3"

개발 워크플로우 최적화

1. .dockerignore 설정으로 빌드 시간 단축
2. 멀티스테이지 빌드 활용
3. 이미지 레이어 캐싱 최적화
4. healthcheck로 서비스 준비 상태 확인

트러블슈팅 체크리스트

즉시 확인 항목

1. docker compose logs - 오류 메시지 확인
2. docker stats - 리소스 사용량 확인
3. docker compose ps - 컨테이너 상태 확인
4. 포트 충돌 여부 확인
5. 디스크 공간 확인

성능 문제 해결 순서

1. ARM 이미지 사용 여부 확인 (M1/M2 Mac)
2. 메모리 제한 설정 확인
3. 볼륨 마운트 최적화
4. 불필요한 이미지 정리
5. 네트워크 설정 재구성

이 가이드는 실제 운영 경험을 바탕으로 한 실용적 지침으로, Docker Compose 사용 시 발생하는 주요 문제점과 해결책을 체계적으로 정리한 것입니다.