kamco-train-api/DEPLOYMENT.md

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 네트워크 생성

# kamco-cds 네트워크 생성 (최초 1회만)
docker network create kamco-cds

# 네트워크 확인
docker network ls | grep kamco-cds

2. SSL 인증서 배치

# 인증서 디렉토리 생성
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. 환경 변수 설정

# .env 파일 생성
cat > .env << EOF
IMAGE_TAG=latest
SPRING_PROFILES_ACTIVE=prod
TZ=Asia/Seoul
EOF

4. 볼륨 디렉토리 생성

# 데이터 디렉토리 생성
mkdir -p ./app/model_output
mkdir -p ./app/train_dataset

# 권한 설정
chmod -R 755 ./app

---

배포 순서

전체 스택 초기 배포

중요: 반드시 아래 순서대로 실행해야 합니다.

# 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

배포 검증

# 서비스별 헬스체크
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 관리

# 설정 변경 후 리로드 (다운타임 없음)
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 서비스 관리

# 재배포 (새 이미지 빌드)
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 서비스 관리

# 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

---

롤백 절차

이미지 기반 롤백

# 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 기반 롤백

# 1. 이전 커밋으로 체크아웃
git log --oneline -10
git checkout <previous-commit-hash>

# 2. 재빌드 및 배포
docker-compose -f docker-compose-prod.yml up -d --build

# 3. 검증 후 브랜치 업데이트 (필요시)
# git checkout develop
# git reset --hard <previous-commit-hash>
# git push -f origin develop

---

모니터링 및 헬스체크

헬스체크 엔드포인트

# 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

컨테이너 상태 모니터링

# 모든 컨테이너 상태
docker ps -a | grep kamco

# 리소스 사용량 실시간 모니터링
docker stats kamco-train-nginx kamco-train-api

# 헬스체크 상태
docker inspect kamco-train-api | grep -A 10 Health

로그 모니터링

# 실시간 로그 (모든 서비스)
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 서비스가 준비되지 않음

# 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 인증서 오류

원인: 인증서 파일 누락 또는 권한 문제

# 인증서 파일 확인
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. 컨테이너 시작 실패

원인: 포트 충돌, 볼륨 권한, 메모리 부족

# 포트 사용 확인
netstat -tulpn | grep -E '80|443|8080'

# 볼륨 권한 확인
ls -la ./app/

# 메모리 사용량 확인
free -h
docker system df

# 해결: 충돌 프로세스 종료 또는 포트 변경
# 메모리 정리
docker system prune -a

4. 네트워크 연결 문제

원인: kamco-cds 네트워크 미생성 또는 컨테이너 미연결

# 네트워크 확인
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 설정 오류

# API 로그에서 DB 연결 에러 확인
docker logs kamco-train-api | grep -i "connection"

# DB 호스트 연결 테스트
docker exec kamco-train-api ping <db-host>

# 해결: 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

---

백업 및 복구

데이터 백업

# 볼륨 데이터 백업
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

이미지 백업

# 현재 이미지 저장
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 - 프로젝트 개발 가이드
• README.md - 프로젝트 개요
• Jenkinsfile-dev - CI/CD 파이프라인
• nginx/nginx.conf - Nginx 설정

---

연락처

문제 발생 시:

1. 로그 수집: docker-compose logs 출력
2. 시스템 정보: docker ps -a, docker network ls
3. 이슈 리포트: GitHub Issues 또는 내부 이슈 트래커