docker-workflow skill

---
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 생성

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

```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% 줄여줍니다:

```dockerfile
# 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)

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

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

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

#### 보안 모범 사례 적용

```dockerfile
# 특정 버전 사용
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`을 생성합니다:

```yaml
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)**:
```yaml
services:
  app:
    build:
      target: development
    volumes:
      - ./src:/app/src
    environment:
      - NODE_ENV=development
    command: npm run dev
```

**운영용 (docker-compose.prod.yml)**:
```yaml
services:
  app:
    build:
      target: production
    restart: always
    environment:
      - NODE_ENV=production
```

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

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

### Phase 4: Build and Run

#### 빌드 명령

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

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

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

#### 실행 명령

```bash
# 단일 컨테이너
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` 유틸리티는 일반적인 디버깅 작업을 제공합니다:

```bash
# 컨테이너 상태 체크
./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
```

#### 일반적인 이슈

**컨테이너가 즉시 종료되는 경우**:
```bash
docker logs myapp
docker run -it --entrypoint sh myapp:latest
```

**네트워크 연결성**:
```bash
docker network inspect myapp_default
docker exec myapp ping db
```

**볼륨 권한**:
```bash
# Dockerfile에서 수정
RUN chown -R nodejs:nodejs /app/data
```

### Phase 6: Optimization

#### 이미지 크기 축소

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

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

#### 빌드 성능

```bash
# 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

```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"]
```

#### 배포 명령

```bash
# 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

```bash
# 빌드
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

```bash
# 조사 (Inspect)
docker inspect myapp

# 상태 (Stats)
docker stats myapp

# 네트워크
docker network inspect bridge

# 볼륨
docker volume ls
```