diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 0000000..e82be35 --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,443 @@ +# KAMCO Train API - Production Deployment Guide + +프로덕션 환경 배포 가이드 + +## 목차 +- [사전 요구사항](#사전-요구사항) +- [초기 설정](#초기-설정) +- [배포 순서](#배포-순서) +- [개별 서비스 관리](#개별-서비스-관리) +- [롤백 절차](#롤백-절차) +- [모니터링 및 헬스체크](#모니터링-및-헬스체크) +- [트러블슈팅](#트러블슈팅) + +--- + +## 사전 요구사항 + +### 시스템 요구사항 +- Docker Engine 20.10+ +- Docker Compose 2.0+ +- 최소 메모리: 4GB +- 디스크 공간: 20GB 이상 + +### 네트워크 요구사항 +- 도메인 설정: + - `train-kamco.com` → 서버 IP (Web UI) + - `api.train-kamco.com` → 서버 IP (API) +- 포트: + - 80 (HTTP) + - 443 (HTTPS) + - 8080 (API - internal) + - 3002 (Web - internal) + +### 필수 파일 +- SSL 인증서: + - `nginx/ssl/train-kamco.com.crt` + - `nginx/ssl/train-kamco.com.key` +- 환경 설정: + - `application-prod.yml` (API 설정) + - `.env` 파일 (IMAGE_TAG 등) + +--- + +## 초기 설정 + +### 1. Docker 네트워크 생성 + +```bash +# kamco-cds 네트워크 생성 (최초 1회만) +docker network create kamco-cds + +# 네트워크 확인 +docker network ls | grep kamco-cds +``` + +### 2. SSL 인증서 배치 + +```bash +# 인증서 디렉토리 생성 +mkdir -p nginx/ssl + +# 인증서 파일 복사 +cp /path/to/train-kamco.com.crt nginx/ssl/ +cp /path/to/train-kamco.com.key nginx/ssl/ + +# 권한 설정 +chmod 600 nginx/ssl/train-kamco.com.key +chmod 644 nginx/ssl/train-kamco.com.crt +``` + +### 3. 환경 변수 설정 + +```bash +# .env 파일 생성 +cat > .env << EOF +IMAGE_TAG=latest +SPRING_PROFILES_ACTIVE=prod +TZ=Asia/Seoul +EOF +``` + +### 4. 볼륨 디렉토리 생성 + +```bash +# 데이터 디렉토리 생성 +mkdir -p ./app/model_output +mkdir -p ./app/train_dataset + +# 권한 설정 +chmod -R 755 ./app +``` + +--- + +## 배포 순서 + +### 전체 스택 초기 배포 + +**중요**: 반드시 아래 순서대로 실행해야 합니다. + +```bash +# 1. Nginx 시작 +docker-compose -f docker-compose-nginx.yml up -d + +# 2. Nginx 상태 확인 +docker ps | grep kamco-train-nginx + +# 3. API 서비스 시작 +docker-compose -f docker-compose-prod.yml up -d + +# 4. API 헬스체크 대기 (최대 40초) +sleep 40 +curl -f http://localhost:8080/monitor/health + +# 5. Web 서비스 시작 (kamco-train-web 프로젝트에서) +# cd ../kamco-train-web +# docker-compose -f docker-compose-prod.yml up -d + +# 6. 전체 상태 확인 +docker ps -a | grep kamco +``` + +### 배포 검증 + +```bash +# 서비스별 헬스체크 +curl -f http://localhost:8080/monitor/health # API (internal) +curl -kf https://api.train-kamco.com/monitor/health # API (external) +curl -kf https://train-kamco.com # Web (external) + +# Nginx 설정 검증 +docker exec kamco-train-nginx nginx -t + +# 로그 확인 +docker-compose -f docker-compose-nginx.yml logs --tail=50 +docker-compose -f docker-compose-prod.yml logs --tail=50 +``` + +--- + +## 개별 서비스 관리 + +### Nginx 관리 + +```bash +# 설정 변경 후 리로드 (다운타임 없음) +docker exec kamco-train-nginx nginx -s reload + +# 재시작 +docker-compose -f docker-compose-nginx.yml restart + +# 로그 확인 +docker-compose -f docker-compose-nginx.yml logs -f + +# 컨테이너 내부 접근 +docker exec -it kamco-train-nginx sh +``` + +### API 서비스 관리 + +```bash +# 재배포 (새 이미지 빌드) +docker-compose -f docker-compose-prod.yml up -d --build + +# 재시작 (이미지 변경 없이) +docker-compose -f docker-compose-prod.yml restart + +# 중지 +docker-compose -f docker-compose-prod.yml down + +# 로그 확인 +docker-compose -f docker-compose-prod.yml logs -f kamco-train-api + +# 컨테이너 내부 접근 +docker exec -it kamco-train-api bash +``` + +### Web 서비스 관리 + +```bash +# kamco-train-web 프로젝트에서 실행 +cd ../kamco-train-web + +# 재배포 +docker-compose -f docker-compose-prod.yml up -d --build + +# 재시작 +docker-compose -f docker-compose-prod.yml restart + +# 로그 확인 +docker-compose -f docker-compose-prod.yml logs -f +``` + +--- + +## 롤백 절차 + +### 이미지 기반 롤백 + +```bash +# 1. 사용 가능한 이미지 확인 +docker images | grep kamco-train-api + +# 2. 이전 이미지 태그로 롤백 +export IMAGE_TAG=previous-commit-hash +docker-compose -f docker-compose-prod.yml up -d + +# 3. 헬스체크 확인 +curl -f http://localhost:8080/monitor/health +``` + +### Git 기반 롤백 + +```bash +# 1. 이전 커밋으로 체크아웃 +git log --oneline -10 +git checkout + +# 2. 재빌드 및 배포 +docker-compose -f docker-compose-prod.yml up -d --build + +# 3. 검증 후 브랜치 업데이트 (필요시) +# git checkout develop +# git reset --hard +# git push -f origin develop +``` + +--- + +## 모니터링 및 헬스체크 + +### 헬스체크 엔드포인트 + +```bash +# API 헬스체크 +curl http://localhost:8080/monitor/health +curl http://localhost:8080/monitor/health/readiness +curl http://localhost:8080/monitor/health/liveness + +# Nginx를 통한 헬스체크 +curl -k https://api.train-kamco.com/monitor/health +``` + +### 컨테이너 상태 모니터링 + +```bash +# 모든 컨테이너 상태 +docker ps -a | grep kamco + +# 리소스 사용량 실시간 모니터링 +docker stats kamco-train-nginx kamco-train-api + +# 헬스체크 상태 +docker inspect kamco-train-api | grep -A 10 Health +``` + +### 로그 모니터링 + +```bash +# 실시간 로그 (모든 서비스) +docker-compose -f docker-compose-nginx.yml logs -f & +docker-compose -f docker-compose-prod.yml logs -f & + +# 에러 로그만 필터링 +docker-compose -f docker-compose-prod.yml logs | grep -i error + +# 최근 100줄 +docker-compose -f docker-compose-prod.yml logs --tail=100 +``` + +--- + +## 트러블슈팅 + +### 1. Nginx 502 Bad Gateway + +**원인**: API 서비스가 준비되지 않음 + +```bash +# API 컨테이너 상태 확인 +docker ps | grep kamco-train-api + +# API 로그 확인 +docker logs kamco-train-api --tail=100 + +# 네트워크 연결 확인 +docker network inspect kamco-cds | grep kamco-train-api + +# 해결: API 재시작 +docker-compose -f docker-compose-prod.yml restart +``` + +### 2. SSL 인증서 오류 + +**원인**: 인증서 파일 누락 또는 권한 문제 + +```bash +# 인증서 파일 확인 +ls -la nginx/ssl/ + +# Nginx 설정 검증 +docker exec kamco-train-nginx nginx -t + +# 해결: 인증서 재배치 및 권한 설정 +chmod 600 nginx/ssl/train-kamco.com.key +chmod 644 nginx/ssl/train-kamco.com.crt +docker-compose -f docker-compose-nginx.yml restart +``` + +### 3. 컨테이너 시작 실패 + +**원인**: 포트 충돌, 볼륨 권한, 메모리 부족 + +```bash +# 포트 사용 확인 +netstat -tulpn | grep -E '80|443|8080' + +# 볼륨 권한 확인 +ls -la ./app/ + +# 메모리 사용량 확인 +free -h +docker system df + +# 해결: 충돌 프로세스 종료 또는 포트 변경 +# 메모리 정리 +docker system prune -a +``` + +### 4. 네트워크 연결 문제 + +**원인**: kamco-cds 네트워크 미생성 또는 컨테이너 미연결 + +```bash +# 네트워크 확인 +docker network ls | grep kamco-cds + +# 네트워크 상세 정보 +docker network inspect kamco-cds + +# 해결: 네트워크 생성 +docker network create kamco-cds + +# 컨테이너를 네트워크에 연결 +docker network connect kamco-cds kamco-train-api +docker network connect kamco-cds kamco-train-nginx +``` + +### 5. 데이터베이스 연결 실패 + +**원인**: application-prod.yml의 DB 설정 오류 + +```bash +# API 로그에서 DB 연결 에러 확인 +docker logs kamco-train-api | grep -i "connection" + +# DB 호스트 연결 테스트 +docker exec kamco-train-api ping + +# 해결: application-prod.yml 수정 후 재배포 +vim src/main/resources/application-prod.yml +docker-compose -f docker-compose-prod.yml up -d --build +``` + +--- + +## Jenkins CI/CD 연동 + +현재 프로젝트는 Jenkins 파이프라인으로 자동 배포됩니다. + +### Jenkinsfile-dev 주요 단계 + +1. **Checkout**: develop 브랜치 체크아웃 +2. **Build**: `./gradlew clean build -x test` +3. **Extract Commit**: IMAGE_TAG로 사용 +4. **Transfer**: 배포 서버로 파일 전송 +5. **Deploy**: Docker Compose 빌드 및 배포 +6. **Health Check**: 30초 대기 후 헬스체크 +7. **Cleanup**: 오래된 이미지 정리 (최신 5개 유지) + +### 배포 서버 정보 + +- **서버**: 192.168.2.109 +- **사용자**: space +- **배포 경로**: `/home/space/kamco-training-api` +- **헬스체크**: `http://localhost:7200/monitor/health` + +--- + +## 백업 및 복구 + +### 데이터 백업 + +```bash +# 볼륨 데이터 백업 +tar -czf backup-$(date +%Y%m%d).tar.gz ./app/model_output ./app/train_dataset + +# 설정 파일 백업 +tar -czf config-backup-$(date +%Y%m%d).tar.gz \ + nginx/nginx.conf \ + nginx/ssl/ \ + src/main/resources/application-prod.yml +``` + +### 이미지 백업 + +```bash +# 현재 이미지 저장 +docker save kamco-train-api:latest | gzip > kamco-train-api-latest.tar.gz + +# 이미지 복구 +gunzip -c kamco-train-api-latest.tar.gz | docker load +``` + +--- + +## 보안 체크리스트 + +- [ ] SSL 인증서 유효기간 확인 +- [ ] nginx/ssl/ 디렉토리 권한 600 +- [ ] application-prod.yml에 DB 비밀번호 암호화 +- [ ] JWT secret key 환경변수로 관리 +- [ ] Docker 소켓 권한 최소화 +- [ ] 방화벽 규칙 설정 (80, 443만 외부 노출) +- [ ] 정기 보안 업데이트 (docker images) + +--- + +## 참고 문서 + +- [CLAUDE.md](./CLAUDE.md) - 프로젝트 개발 가이드 +- [README.md](./README.md) - 프로젝트 개요 +- [Jenkinsfile-dev](./Jenkinsfile-dev) - CI/CD 파이프라인 +- [nginx/nginx.conf](./nginx/nginx.conf) - Nginx 설정 + +--- + +## 연락처 + +문제 발생 시: +1. 로그 수집: `docker-compose logs` 출력 +2. 시스템 정보: `docker ps -a`, `docker network ls` +3. 이슈 리포트: GitHub Issues 또는 내부 이슈 트래커 \ No newline at end of file diff --git a/docker-compose-nginx.yml b/docker-compose-nginx.yml new file mode 100644 index 0000000..4073c64 --- /dev/null +++ b/docker-compose-nginx.yml @@ -0,0 +1,28 @@ +services: + nginx: + image: nginx:alpine + container_name: kamco-train-nginx + ports: + - "80:80" + - "443:443" + volumes: + - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro + - ./nginx/ssl:/etc/nginx/ssl:ro + - nginx-logs:/var/log/nginx + networks: + - kamco-cds + restart: unless-stopped + healthcheck: + test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "--no-check-certificate", "https://localhost/monitor/health"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s + +networks: + kamco-cds: + external: true + +volumes: + nginx-logs: + driver: local \ No newline at end of file