prod
This commit is contained in:
443
DEPLOYMENT.md
Normal file
443
DEPLOYMENT.md
Normal file
@@ -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 <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
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 모니터링 및 헬스체크
|
||||||
|
|
||||||
|
### 헬스체크 엔드포인트
|
||||||
|
|
||||||
|
```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 <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`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 백업 및 복구
|
||||||
|
|
||||||
|
### 데이터 백업
|
||||||
|
|
||||||
|
```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 또는 내부 이슈 트래커
|
||||||
28
docker-compose-nginx.yml
Normal file
28
docker-compose-nginx.yml
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user