diff --git a/CLAUDE.md b/CLAUDE.md index 87903be..5cb7c12 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -273,3 +273,41 @@ Services register themselves with Console on startup and send periodic heartbeat - Console validates tokens and forwards to services - Internal service communication uses service tokens - Rate limiting at API Gateway level + +## Deployment Guide + +### News API Deployment +**IMPORTANT**: News API는 Kubernetes에 배포되며 Docker 이미지 버전 관리가 필요합니다. + +상세 가이드: `services/news-api/DEPLOYMENT.md` 참조 + +#### Quick Deploy +```bash +# 1. 버전 설정 +export VERSION=v1.1.0 + +# 2. 빌드 및 푸시 (버전 태그 + latest) +cd services/news-api +docker build -t yakenator/news-api:${VERSION} -t yakenator/news-api:latest -f backend/Dockerfile backend +docker push yakenator/news-api:${VERSION} +docker push yakenator/news-api:latest + +# 3. Kubernetes 재시작 +kubectl -n site11-news rollout restart deployment news-api-deployment +kubectl -n site11-news rollout status deployment news-api-deployment +``` + +#### Version Management +- **Major (v2.0.0)**: Breaking changes, API 스펙 변경 +- **Minor (v1.1.0)**: 새 기능 추가, 하위 호환성 유지 +- **Patch (v1.0.1)**: 버그 수정, 작은 개선 + +#### Rollback +```bash +# 이전 버전으로 롤백 +kubectl -n site11-news rollout undo deployment news-api-deployment + +# 특정 버전으로 롤백 +kubectl -n site11-news set image deployment/news-api-deployment \ + news-api=yakenator/news-api:v1.0.0 +``` diff --git a/docker-compose.yml b/docker-compose.yml index 10ad421..658a872 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -665,6 +665,94 @@ services: networks: - site11_network + # PostgreSQL for SAPIENS + sapiens-postgres: + image: postgres:16-alpine + container_name: ${COMPOSE_PROJECT_NAME}_sapiens_postgres + environment: + - POSTGRES_DB=sapiens_db + - POSTGRES_USER=sapiens_user + - POSTGRES_PASSWORD=sapiens_password + ports: + - "5433:5432" + volumes: + - ./data/sapiens-postgres:/var/lib/postgresql/data + networks: + - site11_network + restart: unless-stopped + healthcheck: + test: ["CMD-SHELL", "pg_isready -U sapiens_user -d sapiens_db"] + interval: 10s + timeout: 5s + retries: 5 + + # SAPIENS Web Platform + sapiens-web: + build: + context: ./services/sapiens-web + dockerfile: Dockerfile + container_name: ${COMPOSE_PROJECT_NAME}_sapiens_web + ports: + - "3005:5000" + environment: + - NODE_ENV=development + - PORT=5000 + - DATABASE_URL=postgresql://sapiens_user:sapiens_password@sapiens-postgres:5432/sapiens_db + - SESSION_SECRET=sapiens_dev_secret_key_change_in_production + volumes: + - ./services/sapiens-web:/app + - /app/node_modules + networks: + - site11_network + restart: unless-stopped + depends_on: + sapiens-postgres: + condition: service_healthy + + # PostgreSQL for SAPIENS Web2 + sapiens-postgres2: + image: postgres:16-alpine + container_name: ${COMPOSE_PROJECT_NAME}_sapiens_postgres2 + environment: + - POSTGRES_DB=sapiens_db2 + - POSTGRES_USER=sapiens_user2 + - POSTGRES_PASSWORD=sapiens_password2 + ports: + - "5434:5432" + volumes: + - ./data/sapiens-postgres2:/var/lib/postgresql/data + networks: + - site11_network + restart: unless-stopped + healthcheck: + test: ["CMD-SHELL", "pg_isready -U sapiens_user2 -d sapiens_db2"] + interval: 10s + timeout: 5s + retries: 5 + + # SAPIENS Web2 Platform + sapiens-web2: + build: + context: ./services/sapiens-web2 + dockerfile: Dockerfile + container_name: ${COMPOSE_PROJECT_NAME}_sapiens_web2 + ports: + - "3006:5000" + environment: + - NODE_ENV=development + - PORT=5000 + - DATABASE_URL=postgresql://sapiens_user2:sapiens_password2@sapiens-postgres2:5432/sapiens_db2 + - SESSION_SECRET=sapiens2_dev_secret_key_change_in_production + volumes: + - ./services/sapiens-web2:/app + - /app/node_modules + networks: + - site11_network + restart: unless-stopped + depends_on: + sapiens-postgres2: + condition: service_healthy + networks: site11_network: diff --git a/services/news-api/DEPLOYMENT.md b/services/news-api/DEPLOYMENT.md new file mode 100644 index 0000000..0edc0c6 --- /dev/null +++ b/services/news-api/DEPLOYMENT.md @@ -0,0 +1,130 @@ +# News API Deployment Guide + +## 버전 관리 규칙 + +- **Major 버전** (v2.0.0): Breaking changes, API 스펙 변경 +- **Minor 버전** (v1.1.0): 새로운 기능 추가, 하위 호환성 유지 +- **Patch 버전** (v1.0.1): 버그 수정, 작은 개선 + +## 배포 프로세스 + +### 1. 버전 결정 +```bash +# 현재 버전 확인 +cd /Users/jungwoochoi/Desktop/prototype/site11 +git tag | grep news-api | tail -5 + +# 다음 버전 결정 +export VERSION=v1.1.0 # 적절한 버전으로 변경 +``` + +### 2. Docker 이미지 빌드 및 푸시 +```bash +cd /Users/jungwoochoi/Desktop/prototype/site11/services/news-api + +# 버전 태그와 latest 태그 동시 생성 +docker build -t yakenator/news-api:${VERSION} -t yakenator/news-api:latest -f backend/Dockerfile backend + +# 두 태그 모두 푸시 +docker push yakenator/news-api:${VERSION} +docker push yakenator/news-api:latest +``` + +### 3. Kubernetes 배포 +```bash +# 배포 재시작 (latest 태그 사용 시) +kubectl -n site11-news rollout restart deployment news-api-deployment + +# 특정 버전으로 배포 (optional) +kubectl -n site11-news set image deployment/news-api-deployment news-api=yakenator/news-api:${VERSION} + +# 롤아웃 상태 확인 +kubectl -n site11-news rollout status deployment news-api-deployment + +# Pod 상태 확인 +kubectl -n site11-news get pods -l app=news-api +``` + +### 4. 배포 검증 +```bash +# Port forward 설정 +kubectl -n site11-news port-forward svc/news-api-service 8050:8000 & + +# Health check +curl http://localhost:8050/health + +# API 테스트 +curl 'http://localhost:8050/api/v1/ko/articles?page_size=5' +curl 'http://localhost:8050/api/v1/outlets?category=people' +curl 'http://localhost:8050/api/v1/ko/outlets/온유/articles?page_size=5' +``` + +### 5. Git 태그 생성 (optional) +```bash +cd /Users/jungwoochoi/Desktop/prototype/site11 + +# 태그 생성 +git tag -a news-api-${VERSION} -m "News API ${VERSION}: outlet 다국어 지원 및 동적 기사 쿼리" + +# 태그 푸시 +git push origin news-api-${VERSION} +``` + +## 롤백 프로세스 + +### 이전 버전으로 롤백 +```bash +# 이전 버전 확인 +kubectl -n site11-news rollout history deployment news-api-deployment + +# 이전 버전으로 롤백 +kubectl -n site11-news rollout undo deployment news-api-deployment + +# 특정 버전으로 롤백 +kubectl -n site11-news set image deployment/news-api-deployment news-api=yakenator/news-api:v1.0.0 +``` + +## 트러블슈팅 + +### Docker 빌드 실패 +```bash +# Docker daemon 상태 확인 +docker info + +# Docker 재시작 (macOS) +killall Docker && open /Applications/Docker.app +``` + +### Port forward 문제 +```bash +# 기존 port forward 종료 +lsof -ti:8050 | xargs kill -9 2>/dev/null + +# 새로운 port forward 시작 +kubectl -n site11-news port-forward svc/news-api-service 8050:8000 & +``` + +### Pod 상태 확인 +```bash +# Pod 로그 확인 +kubectl -n site11-news logs -f deployment/news-api-deployment + +# Pod 상세 정보 +kubectl -n site11-news describe pod + +# Pod 이벤트 확인 +kubectl -n site11-news get events --sort-by='.lastTimestamp' +``` + +## 버전 히스토리 + +### v1.1.0 (2025-10-12) +- Outlet 다국어 지원 추가 (name_translations, description_translations) +- 동적 기사 쿼리 구현 (entities 필드 활용) +- 정적 articles 배열 제거, source_keyword 기반 동적 조회로 변경 + +### v1.0.0 (Initial Release) +- 다국어 기사 API (ko, en, zh_cn, zh_tw, ja, fr, de, es, it) +- Outlets 관리 (people, topics, companies) +- 댓글 시스템 +- MongoDB 기반 데이터 저장