drama-studio/.claude/skills/deployment-standards.md

# Docker 배포 규칙 (Deployment Standards)

Docker 배포 표준입니다.

## Dockerfile 패턴

### Python 마이크로서비스 (Worker)
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# 필요한 시스템 패키지 설치 (git은 공통 라이브러리 설치에 필요)
RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /var/lib/apt/lists/*

# 의존성 설치 (공통 라이브러리 포함 시)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt && \
    pip install --no-cache-dir git+http://gitea.yakenator.io/yakenator/{공통라이브러리}.git

# 애플리케이션 코드 복사
COPY *.py .

# 워커 실행
CMD ["python", "worker.py"]
```

### Python API 서비스
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# curl은 healthcheck에 필요
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app/ ./app/

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

## docker-compose.yml 패턴

### 서비스 구조
```yaml
services:
  # ===================
  # Infrastructure (독립 포트 사용)
  # ===================
  mongodb:
    image: mongo:7.0
    container_name: {프로젝트}-mongodb
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-admin}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-password123}
    ports:
      - "{호스트포트}:27017"  # 호스트 포트는 충돌 방지를 위해 변경
    volumes:
      - {프로젝트}_mongodb_data:/data/db
    networks:
      - {프로젝트}-network
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### Worker 서비스 패턴
```yaml
  {서비스명}:
    build:
      context: ./repos/{서비스명}
      dockerfile: Dockerfile
    container_name: {프로젝트}-{서비스명}
    restart: unless-stopped
    environment:
      - REDIS_URL=redis://redis:6379
      - MONGODB_URL=mongodb://${MONGO_USER}:${MONGO_PASSWORD}@mongodb:27017/
      - DB_NAME={데이터베이스명}
      - TARGET_COLLECTION={컬렉션명}
    depends_on:
      redis:
        condition: service_healthy
      mongodb:
        condition: service_healthy
    networks:
      - {프로젝트}-network
```

## 컨테이너 네이밍 규칙

- 컨테이너명: `{프로젝트}-{서비스명}`
- 볼륨명: `{프로젝트}_{데이터유형}_data`
- 네트워크: `{프로젝트}-network`

## 환경 변수 관리

- `.env` 파일로 민감 정보 관리
- docker-compose.yml에서 `${VAR:-default}` 형태로 기본값 제공
- 공통 변수: `MONGO_USER`, `MONGO_PASSWORD`, `REDIS_URL`, `JWT_SECRET_KEY`

## 헬스체크 패턴

### Redis
```yaml
healthcheck:
  test: ["CMD", "redis-cli", "ping"]
  interval: 30s
  timeout: 10s
  retries: 3
```

### MongoDB
```yaml
healthcheck:
  test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
  interval: 30s
  timeout: 10s
  retries: 3
```

### FastAPI 서비스
```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
```

## 프라이빗 컨테이너 레지스트리

Docker Hub rate limit 우회 및 프라이빗 이미지 관리를 위해 자체 레지스트리를 사용합니다.

### 레지스트리 구성
| 서비스 | 주소 | 용도 |
|--------|------|------|
| **Private Registry** | `docker.yakenator.io` / `10.0.0.3:5000` | 프라이빗 이미지 Push/Pull |
| **Docker Hub Cache** | `10.0.0.3:5001` | Docker Hub 이미지 캐시 (Pull-through) |
| **Registry UI** | http://reg.yakenator.io | 웹 UI |

### 프라이빗 이미지 Push/Pull (5000)
```bash
# 빌드 후 태깅
docker build -t {이미지명}:{태그} .
docker tag {이미지명}:{태그} 10.0.0.3:5000/{프로젝트}/{이미지명}:{태그}

# Push
docker push 10.0.0.3:5000/{프로젝트}/{이미지명}:{태그}

# 예시
docker build -t drama-studio-api:latest ./audio-studio-api
docker tag drama-studio-api:latest 10.0.0.3:5000/drama-studio/api:latest
docker push 10.0.0.3:5000/drama-studio/api:latest
```

### Docker Hub 캐시 사용 (5001)
```bash
# Docker Hub 이미지를 캐시 경유로 pull (rate limit 우회)
docker pull 10.0.0.3:5001/library/mongo:7.0
docker pull 10.0.0.3:5001/library/redis:7-alpine
docker pull 10.0.0.3:5001/library/python:3.11-slim

# 공식 이미지는 library/ 접두사 사용
docker pull 10.0.0.3:5001/library/node:20-alpine

# 사용자 이미지는 {username}/ 접두사 사용
docker pull 10.0.0.3:5001/joxit/docker-registry-ui:latest
```

### docker-compose.yml에서 사용
```yaml
services:
  # 프라이빗 이미지 사용
  api:
    image: 10.0.0.3:5000/{프로젝트}/api:latest

  # Docker Hub 캐시 이미지 사용
  mongodb:
    image: 10.0.0.3:5001/library/mongo:7.0

  redis:
    image: 10.0.0.3:5001/library/redis:7-alpine
```

### Docker 데몬 설정 (Insecure Registry)
```bash
# /etc/docker/daemon.json
{
  "insecure-registries": ["10.0.0.3:5000", "10.0.0.3:5001"]
}

# 설정 후 재시작
sudo systemctl restart docker
```

### CI/CD에서 사용
```bash
# 빌드 및 배포 스크립트 예시
VERSION=$(git rev-parse --short HEAD)
IMAGE="10.0.0.3:5000/${PROJECT}/${SERVICE}:${VERSION}"

docker build -t $IMAGE .
docker push $IMAGE
docker tag $IMAGE 10.0.0.3:5000/${PROJECT}/${SERVICE}:latest
docker push 10.0.0.3:5000/${PROJECT}/${SERVICE}:latest
```

## 참고 리포지토리

- Gitea: http://gitea.yakenator.io/yakenator/
- Container Registry: http://reg.yakenator.io
- Docker Registry API: http://docker.yakenator.io/v2/_catalog