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

이미지 크기 축소

전략:

• 더 작은 베이스 이미지 사용 (alpine > slim > debian)

• 빌드 도구 제외를 위해 멀티 스테이지 빌드 활용

• 레이어 수를 줄이기 위해 RUN 명령 결합

• 동일한 레이어 내에서 정리(Clean up) 수행

• .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