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 -dPhase 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 -vPhase 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/dataPhase 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 --parallelPhase 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 appCommon 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 -aDebugging
# 조사 (Inspect)
docker inspect myapp
# 상태 (Stats)
docker stats myapp
# 네트워크
docker network inspect bridge
# 볼륨
docker volume ls