From 9e80618005c491fc787c042041b744c51d345820 Mon Sep 17 00:00:00 2001
From: jungwoo choi <jungwoochoi@iMac192.local>
Date: Sun, 28 Sep 2025 20:45:51 +0900
Subject: [PATCH] docs: Add comprehensive README with detailed build and
 deployment instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 시스템 요구사항 및 포트 사용 정보
- 단계별 설치 가이드 (Quick Start & Detailed)
- 서비스 아키텍처 설명
- 개별 서비스 관리 방법
- 환경 설정 (API 키 등)
- 개발 가이드 및 테스트
- 상세한 문제 해결 가이드
- Git 저장소 관리 방법
- 모니터링 및 백업 가이드
---
 README.md | 443 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 422 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 4dcaa96..fcc3a66 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,430 @@
-# Site11 - Microservices Architecture
+# Site11 - Multi-Language News Platform with Microservices Architecture
 
-## Overview
-Microservices platform with Console as API Gateway orchestrating multiple domain services.
+## 📋 목차 (Table of Contents)
+- [개요 (Overview)](#개요-overview)
+- [시스템 요구사항 (System Requirements)](#시스템-요구사항-system-requirements)
+- [빠른 시작 (Quick Start)](#빠른-시작-quick-start)
+- [상세 설치 가이드 (Detailed Installation)](#상세-설치-가이드-detailed-installation)
+- [서비스 구조 (Service Architecture)](#서비스-구조-service-architecture)
+- [서비스 관리 (Service Management)](#서비스-관리-service-management)
+- [환경 설정 (Configuration)](#환경-설정-configuration)
+- [개발 가이드 (Development Guide)](#개발-가이드-development-guide)
+- [문제 해결 (Troubleshooting)](#문제-해결-troubleshooting)
+- [Git 저장소 관리 (Repository Management)](#git-저장소-관리-repository-management)
 
-## Quick Start
+## 개요 (Overview)
 
-### Start Services
-```bash
-# Start console service
-docker-compose up -d console-backend
+Site11은 다국어 뉴스 콘텐츠를 자동으로 수집, 번역, 생성하는 마이크로서비스 기반 플랫폼입니다.
 
-# Check status
-curl http://localhost:8011/health
+### 주요 기능
+- 🌐 8개 언어 자동 번역 (한국어, 영어, 중국어, 일본어, 프랑스어, 독일어, 스페인어, 이탈리아어)
+- 📰 실시간 뉴스 수집 및 AI 기반 콘텐츠 생성
+- 🎨 자동 이미지 생성 및 최적화
+- 🔄 비동기 작업 처리 파이프라인
+- 📊 실시간 모니터링 및 통계
+
+## 시스템 요구사항 (System Requirements)
+
+### 필수 요구사항
+- **Docker**: 20.10.0 이상
+- **Docker Compose**: 2.0.0 이상
+- **메모리**: 최소 8GB RAM (16GB 권장)
+- **디스크**: 최소 50GB 여유 공간
+- **OS**: Linux, macOS, Windows with WSL2
+
+### 포트 사용
+```
+- 80: Nginx (Reverse Proxy)
+- 8000-8100: 마이크로서비스 백엔드
+- 3000-3100: 프론트엔드 서비스
+- 27017: MongoDB
+- 6379: Redis
+- 9092: Kafka
+- 2181: Zookeeper
+- 9000: MinIO
+- 8983: Solr
 ```
 
-### Available Endpoints
-- `http://localhost:8011/` - Root endpoint
-- `http://localhost:8011/health` - Health check
-- `http://localhost:8011/api/status` - System status
+## 빠른 시작 (Quick Start)
 
-## Architecture
-- **Console**: API Gateway and orchestrator
-- **Services**: Domain-specific microservices (users, oauth, images, etc.)
-- **Database**: MongoDB for persistence
-- **Cache**: Redis for caching and pub/sub
+### 1. 저장소 클론
+```bash
+# HTTPS
+git clone http://gitea.yakenator.io/aimond/site11.git
 
-## Development
-See `docs/PLAN.md` for implementation roadmap and `docs/PROGRESS.md` for current status.
\ No newline at end of file
+# 디렉토리 이동
+cd site11
+```
+
+### 2. 환경 변수 설정
+```bash
+# .env 파일 생성
+cp .env.example .env
+
+# 필수 환경 변수 설정
+echo "COMPOSE_PROJECT_NAME=site11" >> .env
+echo "DEEPL_API_KEY=your-deepl-api-key" >> .env
+echo "OPENAI_API_KEY=your-openai-api-key" >> .env
+```
+
+### 3. 전체 시스템 시작
+```bash
+# 모든 서비스 빌드 및 시작 (백그라운드)
+docker-compose up -d --build
+
+# 상태 확인
+docker-compose ps
+
+# 로그 확인
+docker-compose logs -f
+```
+
+### 4. 서비스 확인
+```bash
+# 헬스 체크
+curl http://localhost:8000/health
+
+# MongoDB 연결 확인
+docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"
+```
+
+## 상세 설치 가이드 (Detailed Installation)
+
+### 단계별 서비스 시작
+
+#### 1단계: 핵심 인프라
+```bash
+# MongoDB, Redis, Kafka 시작
+docker-compose up -d mongodb redis zookeeper kafka
+
+# 인프라 준비 대기 (약 30초)
+sleep 30
+
+# 상태 확인
+docker-compose ps mongodb redis kafka
+```
+
+#### 2단계: Pipeline 서비스
+```bash
+# Pipeline 서비스 시작
+docker-compose up -d pipeline-scheduler pipeline-monitor \
+  pipeline-rss-collector pipeline-google-search \
+  pipeline-ai-generator pipeline-translator \
+  pipeline-image-generator
+
+# Pipeline 모니터 확인
+curl http://localhost:8100/status
+```
+
+#### 3단계: 뉴스 서비스
+```bash
+# 국가별 뉴스 서비스
+docker-compose up -d korea-backend korea-frontend \
+  usa-backend usa-frontend \
+  japan-backend japan-frontend \
+  china-backend china-frontend
+
+# 기업 뉴스 서비스
+docker-compose up -d samsung-backend samsung-frontend \
+  apple-backend apple-frontend \
+  google-backend google-frontend
+```
+
+#### 4단계: 아티스트 서비스
+```bash
+# K-POP 아티스트 서비스
+docker-compose up -d k-culture-backend \
+  blackpink-backend blackpink-frontend \
+  ive-backend ive-frontend \
+  twice-backend twice-frontend
+```
+
+## 서비스 구조 (Service Architecture)
+
+### 핵심 인프라
+- **MongoDB**: 데이터 저장소
+- **Redis**: 캐시 및 작업 큐
+- **Kafka**: 이벤트 스트리밍
+- **MinIO**: 이미지/파일 저장소
+- **Solr**: 검색 엔진
+
+### Pipeline 서비스
+```
+pipeline-scheduler (8099)
+  ├── pipeline-rss-collector     # RSS 피드 수집
+  ├── pipeline-google-search     # Google 검색 수집
+  ├── pipeline-ai-generator      # AI 콘텐츠 생성
+  ├── pipeline-translator        # 다국어 번역
+  └── pipeline-image-generator   # 이미지 생성
+
+pipeline-monitor (8100)          # 실시간 모니터링
+```
+
+### 콘텐츠 서비스
+- **Media Empire** (8200/3200): 통합 다국어 뉴스 포털
+- **국가별 서비스**: Korea, USA, Japan, China
+- **기업 서비스**: Samsung, Apple, Google, LG, Musk, WSJ
+- **아티스트 서비스**: K-Culture, Blackpink, IVE, Twice 등
+
+## 서비스 관리 (Service Management)
+
+### 개별 서비스 관리
+```bash
+# 특정 서비스만 시작
+docker-compose up -d [service-name]
+
+# 특정 서비스 재시작
+docker-compose restart [service-name]
+
+# 특정 서비스 중지
+docker-compose stop [service-name]
+
+# 서비스 로그 확인
+docker-compose logs -f [service-name]
+
+# 서비스 재빌드
+docker-compose build [service-name]
+docker-compose up -d [service-name]
+```
+
+### 데이터베이스 관리
+```bash
+# MongoDB 접속
+docker exec -it site11_mongodb mongosh
+
+# 데이터베이스 목록
+show dbs
+
+# AI Writer DB 사용
+use ai_writer_db
+
+# 컬렉션 확인
+show collections
+
+# 기사 수 확인
+db.articles_ko.countDocuments()
+```
+
+### Redis 관리
+```bash
+# Redis CLI 접속
+docker exec -it site11_redis redis-cli
+
+# 모든 키 확인
+KEYS *
+
+# 큐 상태 확인
+LLEN queue:google_search
+LLEN queue:ai_generation
+LLEN queue:translation
+```
+
+## 환경 설정 (Configuration)
+
+### 필수 API 키 설정
+```bash
+# .env 파일 편집
+vim .env
+
+# 필수 설정
+DEEPL_API_KEY=your-deepl-api-key        # 번역 API
+OPENAI_API_KEY=your-openai-api-key      # 이미지 생성
+CLAUDE_API_KEY=your-claude-api-key      # AI 콘텐츠 생성
+SERP_API_KEY=your-serp-api-key          # Google 검색
+```
+
+### Pipeline 설정
+```bash
+# services/pipeline/.env
+WORKER_COUNT=3                           # 워커 프로세스 수
+BATCH_SIZE=10                           # 배치 처리 크기
+TRANSLATION_DELAY=1.0                   # 번역 지연 시간
+```
+
+## 개발 가이드 (Development Guide)
+
+### 새 서비스 추가
+```bash
+# 서비스 디렉토리 구조
+services/
+  └── new-service/
+      ├── backend/
+      │   ├── Dockerfile
+      │   ├── requirements.txt
+      │   └── main.py
+      └── frontend/
+          ├── Dockerfile
+          ├── package.json
+          └── src/
+```
+
+### 로컬 개발 환경
+```bash
+# 백엔드 개발 (Python)
+cd services/[service-name]/backend
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+python main.py
+
+# 프론트엔드 개발 (React)
+cd services/[service-name]/frontend
+npm install
+npm run dev
+```
+
+### 테스트 실행
+```bash
+# 통합 테스트
+python test_integration.py
+
+# Pipeline 테스트
+python services/pipeline/test_pipeline.py
+
+# 특정 서비스 테스트
+docker exec -it site11_[service-name] pytest
+```
+
+## 문제 해결 (Troubleshooting)
+
+### 서비스가 시작되지 않을 때
+```bash
+# 포트 충돌 확인
+lsof -i :8000
+
+# 컨테이너 상태 확인
+docker ps -a | grep site11
+
+# 오류 로그 확인
+docker-compose logs [service-name] | tail -100
+```
+
+### MongoDB 연결 문제
+```bash
+# MongoDB 상태 확인
+docker exec -it site11_mongodb mongosh --eval "db.serverStatus()"
+
+# 연결 테스트
+docker run --rm -it --network site11_network mongo:7.0 mongosh mongodb://mongodb:27017
+```
+
+### 메모리 부족 문제
+```bash
+# Docker 리소스 정리
+docker system prune -a
+
+# 불필요한 이미지 삭제
+docker image prune -a
+
+# 컨테이너 로그 정리
+docker-compose logs --tail=0 --follow
+```
+
+### Pipeline 작업 막힘
+```bash
+# Redis 큐 확인
+docker exec -it site11_redis redis-cli
+> LLEN queue:translation
+> LPOP queue:translation  # 막힌 작업 제거
+
+# Pipeline 재시작
+docker-compose restart pipeline-scheduler pipeline-translator
+```
+
+## Git 저장소 관리 (Repository Management)
+
+### .gitignore 설정
+```
+# 대용량 파일 제외
+backups/
+*.archive
+*.log
+data/
+
+# 이미지 파일 제외
+*.png
+*.jpg
+*.jpeg
+
+# Node modules 제외
+node_modules/
+**/node_modules/
+
+# 환경 파일
+.env
+*.env.local
+```
+
+### 저장소 정리
+```bash
+# Git 히스토리 정리
+git gc --aggressive --prune=now
+
+# 대용량 파일 찾기
+find . -size +100M -type f
+
+# 캐시 정리
+git rm -r --cached [file/folder]
+```
+
+## 모니터링 (Monitoring)
+
+### Pipeline 모니터링
+- URL: http://localhost:8100
+- 실시간 큐 상태 확인
+- 처리 통계 확인
+
+### 로그 모니터링
+```bash
+# 전체 로그 스트림
+docker-compose logs -f
+
+# 특정 서비스 로그
+docker-compose logs -f pipeline-scheduler
+
+# 에러만 필터링
+docker-compose logs -f 2>&1 | grep ERROR
+```
+
+### 성능 모니터링
+```bash
+# 컨테이너 리소스 사용량
+docker stats
+
+# MongoDB 성능
+docker exec -it site11_mongodb mongosh --eval "db.serverStatus().opcounters"
+```
+
+## 백업 및 복구 (Backup & Recovery)
+
+### MongoDB 백업
+```bash
+# 백업 스크립트 실행
+./scripts/backup-mongodb.sh
+
+# 수동 백업
+docker exec -it site11_mongodb mongodump --archive=/data/backup.archive
+docker cp site11_mongodb:/data/backup.archive ./backups/
+```
+
+### 전체 시스템 백업
+```bash
+# 데이터 디렉토리 백업
+tar -czf backup-$(date +%Y%m%d).tar.gz data/
+
+# 설정 백업
+tar -czf config-backup.tar.gz .env docker-compose.yml services/
+```
+
+## 문의 및 지원 (Support)
+
+- **이슈 트래커**: http://gitea.yakenator.io/aimond/site11/issues
+- **문서**: `/docs` 디렉토리 참조
+  - `PLAN.md`: 구현 계획
+  - `PROGRESS.md`: 진행 상황
+  - `ARCHITECTURE.md`: 시스템 구조
+  - `PIPELINE_SCHEDULER_GUIDE.md`: Pipeline 가이드
+
+## 라이선스 (License)
+
+Copyright (c) 2024 Site11 Project. All rights reserved.
\ No newline at end of file