From 07579ea9f5881cee22697a3cb78e65528055d5da Mon Sep 17 00:00:00 2001
From: jungwoo choi <jungwoochoi@iMac192.local>
Date: Wed, 22 Oct 2025 09:20:55 +0900
Subject: [PATCH] docs: Add News API deployment guide and SAPIENS services
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add comprehensive deployment guide in CLAUDE.md
  - Quick deploy commands for News API
  - Version management strategy (Major/Minor/Patch)
  - Rollback procedures
- Add detailed DEPLOYMENT.md for News API service
- Update docker-compose.yml with SAPIENS platform services
  - Add sapiens-web with PostgreSQL (port 3005, 5433)
  - Add sapiens-web2 with PostgreSQL (port 3006, 5434)
  - Configure health checks and dependencies

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md                       |  38 ++++++++++
 docker-compose.yml              |  88 +++++++++++++++++++++
 services/news-api/DEPLOYMENT.md | 130 ++++++++++++++++++++++++++++++++
 3 files changed, 256 insertions(+)
 create mode 100644 services/news-api/DEPLOYMENT.md

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-name>
+
+# 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 기반 데이터 저장