docker-workflow

name	docker-workflow
description	멀티 스테이지 빌드(multi-stage builds), docker-compose 오케스트레이션, 이미지 최적화, 디버깅 및 운영 모범 사례를 포함하는 포괄적인 Docker 컨테이너화 워크플로우입니다. 애플리케이션 컨테이너화, 개발 환경 구축 또는 Docker 배포 시 사용합니다.

Docker Workflow

Overview

Docker 컨테이너화는 애플리케이션과 그 종속성을 이식 가능하고 재현 가능한 컨테이너로 패키징하여 개발, 테스트 및 배포를 능률화합니다. 이 SKILL은 개발부터 운영에 이르기까지 전문적인 Docker 워크플로우를 안내합니다.

Core Capabilities

• 멀티 스테이지 빌드 (Multi-stage builds): 최적의 이미지 크기를 위해 빌드와 런타임 종속성을 분리합니다.
• Docker Compose 오케스트레이션: 네트워킹과 종속성을 갖춘 다중 컨테이너 애플리케이션을 관리합니다.
• 이미지 최적화: 모범 사례를 통해 이미지 크기를 50-90% 줄입니다.
• 개발 워크플로우: Hot-reload, 볼륨 마운트 및 환경별 설정을 지원합니다.
• 디버깅 도구: 컨테이너 조사, health checks 및 트러블슈팅 유틸리티를 제공합니다.
• 운영 준비 (Production readiness): 보안 강화(Security hardening), health checks 및 배포 전략을 다룹니다.

When to Use This Skill

다음을 수행할 때 활성화하세요:

• 새로운 애플리케이션 컨테이너화
• Docker로 개발 환경 구축
• 운영 환경에 적합한 Docker 이미지 생성
• 다중 컨테이너 애플리케이션 오케스트레이션
• 컨테이너 이슈 디버깅
• Docker 빌드 및 이미지 최적화

Workflow Phases

Phase 1: Initial Setup

.dockerignore 생성

빌드 컨텍스트에서 불필요한 파일을 제외합니다:

node_modules/
__pycache__/
*.pyc
.git/
.env
*.log
dist/
build/
coverage/

포괄적인 템플릿은 examples/.dockerignore를 참조하세요.

핵심 원칙:

• 빌드 아티팩트 및 종속성 제외
• 민감한 파일(.env, 자격 증명) 제외
• 버전 관리 시스템(.git) 제외
• 컨텍스트 크기 축소 = 빌드 속도 향상

애플리케이션 요구 사항 분석

다음을 결정합니다:

• 런타임 (Node.js, Python, Go, Java)
• 종속성 및 패키지 매니저
• 빌드 요구 사항 vs 런타임 요구 사항
• 포트 노출 및 볼륨 필요성

Phase 2: Multi-Stage Dockerfile

전략 선택

멀티 스테이지 빌드는 최종 이미지 크기를 50-90% 줄여줍니다:

# Stage 1: Build
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:18-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

Node.js, Python, Go, Java, Rust 템플릿은 examples/Dockerfile.multi-stage를 참조하세요.

레이어 캐싱 최적화 (Optimize Layer Caching)

순서가 중요합니다 - 자주 변경되는 콘텐츠는 마지막에 배치하세요:

# ✅ 좋음: 종속성이 별도로 캐시됨
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

# ❌ 나쁨: 파일이 하나만 변경되어도 캐시가 무효화됨
COPY . .
RUN npm ci

보안 모범 사례 적용

# 특정 버전 사용
FROM node:18.17.1-alpine

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

# 소유권과 함께 복사
COPY --chown=nodejs:nodejs . .

보안 체크리스트:

• 베이스 이미지 버전 고정 (Pin versions)
• 최소한의 베이스 이미지 사용 (alpine, slim)
• non-root 사용자로 실행
• 취약점 스캔 실시
• 설치 패키지 최소화

Phase 3: Docker Compose Setup

서비스 정의

docker-compose.yml을 생성합니다:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://db:5432/myapp
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./src:/app/src  # 개발 시 hot-reload
    networks:
      - app-network

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: myapp
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 5s
    networks:
      - app-network

volumes:
  postgres-data:

networks:
  app-network:

모니터링, 큐, 캐싱이 포함된 전체 기능 설정은 examples/docker-compose.yml을 참조하세요.

환경 설정

환경별로 override 파일을 사용합니다:

개발용 (docker-compose.override.yml):

services:
  app:
    build:
      target: development
    volumes:
      - ./src:/app/src
    environment:
      - NODE_ENV=development
    command: npm run dev

운영용 (docker-compose.prod.yml):

services:
  app:
    build:
      target: production
    restart: always
    environment:
      - NODE_ENV=production

사용법:

# 개발 (override 파일이 자동으로 사용됨)
docker-compose up

# 운영
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Phase 4: Build and Run

빌드 명령

# 기본 빌드
docker build -t myapp:latest .

# 특정 스테이지 빌드
docker build --target production -t myapp:prod .

# BuildKit을 사용한 빌드 (빠름)
DOCKER_BUILDKIT=1 docker build -t myapp:latest .

실행 명령

# 단일 컨테이너
docker run -d -p 3000:3000 -e NODE_ENV=production myapp:latest

# Docker Compose
docker-compose up -d

# 로그 확인
docker-compose logs -f app

# 컨테이너 내 명령 실행
docker-compose exec app sh

# 중지 및 제거
docker-compose down -v

Phase 5: Debugging and Troubleshooting

Helper 스크립트 사용

scripts/docker_helper.sh 유틸리티는 일반적인 디버깅 작업을 제공합니다:

# 컨테이너 상태 체크
./scripts/docker_helper.sh health myapp

# 상세 정보 조사
./scripts/docker_helper.sh inspect myapp

# 로그 확인
./scripts/docker_helper.sh logs myapp 200

# Shell 열기
./scripts/docker_helper.sh shell myapp

# 이미지 크기 분석
./scripts/docker_helper.sh size myapp:latest

# 리소스 정리 (Cleanup)
./scripts/docker_helper.sh cleanup

일반적인 이슈

컨테이너가 즉시 종료되는 경우:

docker logs myapp
docker run -it --entrypoint sh myapp:latest

네트워크 연결성:

docker network inspect myapp_default
docker exec myapp ping db

볼륨 권한:

# Dockerfile에서 수정
RUN chown -R nodejs:nodejs /app/data

Phase 6: Optimization

이미지 크기 축소

전략:

1. 더 작은 베이스 이미지 사용 (alpine > slim > debian)
2. 빌드 도구 제외를 위해 멀티 스테이지 빌드 활용
3. 레이어 수를 줄이기 위해 RUN 명령 결합
4. 동일한 레이어 내에서 정리(Clean up) 수행
5. .dockerignore 활용

예시:

# ✅ 좋음: 결합 및 정리 완료
RUN apt-get update && \
    apt-get install -y --no-install-recommends package1 && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

빌드 성능

# BuildKit 활성화
export DOCKER_BUILDKIT=1

# 캐시 마운트(Cache mounts) 사용
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# 병렬 빌드
docker-compose build --parallel

Phase 7: Production Deployment

운영 환경용 Dockerfile

FROM node:18-alpine AS production

# 보안: non-root 사용자
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001

WORKDIR /app
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
USER nodejs

# Health check
HEALTHCHECK --interval=30s --timeout=3s \
  CMD node healthcheck.js

EXPOSE 3000
CMD ["node", "dist/index.js"]

배포 명령

# Registry용 태그 지정
docker tag myapp:latest registry.example.com/myapp:v1.0.0

# Registry로 Push
docker push registry.example.com/myapp:v1.0.0

# 배포
docker-compose pull && docker-compose up -d

# 무중단 업데이트 (Rolling update)
docker-compose up -d --no-deps --build app

Common Patterns

Full-Stack Application

• Frontend + Backend + Database + Redis
• examples/docker-compose.yml 참조

Microservices

• API Gateway + Multiple Services + Message Queue
• 네트워크 격리(Network isolation) 및 서비스 검색(Service discovery)

개발 시 Hot Reload 적용

• 소스 코드를 위한 볼륨 마운트
• 개발 설정을 위한 override 파일

Best Practices Summary

Security (보안)

✅ latest가 아닌 구체적인 이미지 버전 사용 ✅ non-root 사용자로 실행 ✅ 민감한 데이터에는 secrets management 사용 ✅ 이미지의 취약점 스캔 실시 ✅ 최소한의 베이스 이미지 사용

Performance (성능)

✅ 멀티 스테이지 빌드 사용 ✅ 레이어 캐싱 최적화 ✅ .dockerignore 사용 ✅ RUN 명령 결합 ✅ BuildKit 사용

Development (개발)

✅ 다중 컨테이너 앱에 docker-compose 사용 ✅ hot-reload를 위해 볼륨(Volumes) 사용 ✅ health checks 구현 ✅ 적절한 종속성 순서 적용

Production (운영)

✅ 재시작 정책(Restart policies) 설정 ✅ 오케스트레이션(Swarm, Kubernetes) 사용 ✅ health checks로 모니터링 ✅ Reverse proxy 사용 ✅ Rolling updates 구현

Helper Resources

• scripts/docker_helper.sh: 컨테이너 조사, health checks, 자동화
• examples/Dockerfile.multi-stage: Node.js, Python, Go, Java, Rust용 템플릿
• examples/docker-compose.yml: 전체 기능을 갖춘 멀티 서비스 설정
• examples/.dockerignore: 포괄적인 무시(Ignore) 패턴

Quick Reference

Essential Commands

# 빌드
docker build -t myapp .
docker-compose build

# 실행
docker run -d -p 3000:3000 myapp
docker-compose up -d

# 로그
docker logs -f myapp
docker-compose logs -f

# 실행 (Execute)
docker exec -it myapp sh
docker-compose exec app sh

# 중지
docker-compose down

# 정리 (Clean)
docker system prune -a

Debugging

# 조사 (Inspect)
docker inspect myapp

# 상태 (Stats)
docker stats myapp

# 네트워크
docker network inspect bridge

# 볼륨
docker volume ls