feat: Drama Studio 프로젝트 초기 구조 설정

- FastAPI 백엔드 (audio-studio-api) - Next.js 프론트엔드 (audio-studio-ui) - Qwen3-TTS 엔진 (audio-studio-tts) - MusicGen 서비스 (audio-studio-musicgen) - Docker Compose 개발/운영 환경 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 11:39:38 +09:00
commit cc547372c0
70 changed files with 18399 additions and 0 deletions
--- a/.claude/skills/deployment-standards.md
+++ b/.claude/skills/deployment-standards.md
@ -0,0 +1,220 @@
+# 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