prod
This commit is contained in:
415
DEPLOY.md
Normal file
415
DEPLOY.md
Normal file
@@ -0,0 +1,415 @@
|
||||
# KAMCO Training API 배포 가이드 (RedHat 9.6)
|
||||
|
||||
## 빠른 배포 (Quick Start)
|
||||
|
||||
이 문서는 RedHat 9.6 환경에서 HTTPS로 KAMCO Training API를 배포하는 방법을 설명합니다.
|
||||
|
||||
**접속 URL**:
|
||||
- `https://api.train-kamco.com`
|
||||
- `https://train-kamco.com`
|
||||
|
||||
## 사전 요구사항
|
||||
|
||||
- [x] Docker & Docker Compose 설치
|
||||
- [x] Git 설치
|
||||
- [x] sudo 권한
|
||||
- [x] 포트 80, 443 사용 가능
|
||||
|
||||
## 1단계: /etc/hosts 설정
|
||||
|
||||
```bash
|
||||
# root 권한으로 도메인 추가
|
||||
echo "127.0.0.1 api.train-kamco.com train-kamco.com" | sudo tee -a /etc/hosts
|
||||
|
||||
# 확인
|
||||
cat /etc/hosts | grep train-kamco
|
||||
```
|
||||
|
||||
**예상 결과**:
|
||||
```
|
||||
127.0.0.1 api.train-kamco.com train-kamco.com
|
||||
```
|
||||
|
||||
## 2단계: 방화벽 설정 (필요시)
|
||||
|
||||
```bash
|
||||
# 방화벽 상태 확인
|
||||
sudo firewall-cmd --state
|
||||
|
||||
# HTTP/HTTPS 포트 개방
|
||||
sudo firewall-cmd --permanent --add-port=80/tcp
|
||||
sudo firewall-cmd --permanent --add-port=443/tcp
|
||||
|
||||
# 방화벽 재로드
|
||||
sudo firewall-cmd --reload
|
||||
|
||||
# 확인
|
||||
sudo firewall-cmd --list-ports
|
||||
```
|
||||
|
||||
**예상 결과**: `80/tcp 443/tcp`
|
||||
|
||||
## 3단계: 프로젝트 디렉토리로 이동
|
||||
|
||||
```bash
|
||||
cd /path/to/kamco-train-api
|
||||
|
||||
# 현재 위치 확인
|
||||
pwd
|
||||
# 예상: /home/username/kamco-train-api
|
||||
```
|
||||
|
||||
## 4단계: 파일 구조 확인
|
||||
|
||||
배포 전 필수 파일이 모두 있는지 확인하세요:
|
||||
|
||||
```bash
|
||||
# SSL 인증서 확인
|
||||
ls -la nginx/ssl/
|
||||
|
||||
# 예상 결과:
|
||||
# train-kamco.com.crt (인증서)
|
||||
# train-kamco.com.key (개인 키)
|
||||
# openssl.cnf (설정 파일)
|
||||
```
|
||||
|
||||
```bash
|
||||
# Docker Compose 파일 확인
|
||||
ls -la docker-compose-prod.yml nginx/nginx.conf
|
||||
|
||||
# 예상: 두 파일 모두 존재
|
||||
```
|
||||
|
||||
## 5단계: Docker 네트워크 생성 (최초 1회)
|
||||
|
||||
```bash
|
||||
# kamco-cds 네트워크가 있는지 확인
|
||||
docker network ls | grep kamco-cds
|
||||
|
||||
# 없으면 생성
|
||||
docker network create kamco-cds
|
||||
```
|
||||
|
||||
## 6단계: Docker Compose 배포
|
||||
|
||||
```bash
|
||||
# 기존 컨테이너 중지 (있는 경우)
|
||||
docker-compose -f docker-compose-prod.yml down
|
||||
|
||||
# 새로운 이미지 빌드 및 실행
|
||||
docker-compose -f docker-compose-prod.yml up -d --build
|
||||
|
||||
# 컨테이너 상태 확인
|
||||
docker-compose -f docker-compose-prod.yml ps
|
||||
```
|
||||
|
||||
**예상 결과**:
|
||||
```
|
||||
NAME STATUS
|
||||
kamco-cd-nginx Up (healthy)
|
||||
kamco-cd-training-api Up (healthy)
|
||||
```
|
||||
|
||||
## 7단계: 배포 확인
|
||||
|
||||
### 컨테이너 로그 확인
|
||||
|
||||
```bash
|
||||
# Nginx 로그
|
||||
docker logs kamco-cd-nginx --tail 50
|
||||
|
||||
# API 로그
|
||||
docker logs kamco-cd-training-api --tail 50
|
||||
|
||||
# 실시간 로그 (Ctrl+C로 종료)
|
||||
docker-compose -f docker-compose-prod.yml logs -f
|
||||
```
|
||||
|
||||
### HTTP → HTTPS 리다이렉트 테스트
|
||||
|
||||
```bash
|
||||
# HTTP 접속 시 HTTPS로 리다이렉트되는지 확인
|
||||
curl -I http://api.train-kamco.com
|
||||
curl -I http://train-kamco.com
|
||||
|
||||
# 예상 결과: 301 Moved Permanently
|
||||
# Location: https://api.train-kamco.com/ 또는 https://train-kamco.com/
|
||||
```
|
||||
|
||||
### HTTPS 헬스체크
|
||||
|
||||
```bash
|
||||
# -k 플래그: 사설 인증서 경고 무시
|
||||
curl -k https://api.train-kamco.com/monitor/health
|
||||
curl -k https://train-kamco.com/monitor/health
|
||||
|
||||
# 예상 결과: {"status":"UP","components":{...}}
|
||||
```
|
||||
|
||||
### 브라우저 테스트
|
||||
|
||||
브라우저에서 다음 URL에 접속:
|
||||
|
||||
- `https://api.train-kamco.com/monitor/health`
|
||||
- `https://train-kamco.com/monitor/health`
|
||||
|
||||
**사설 인증서 경고**:
|
||||
- "안전하지 않음" 경고가 표시되면 **"고급"** → **"계속 진행"** 클릭
|
||||
|
||||
## 8단계: SSL 인증서 확인 (선택사항)
|
||||
|
||||
```bash
|
||||
# 인증서 정보 확인
|
||||
openssl x509 -in nginx/ssl/train-kamco.com.crt -text -noout | head -30
|
||||
|
||||
# 유효 기간 확인 (100년)
|
||||
openssl x509 -in nginx/ssl/train-kamco.com.crt -noout -dates
|
||||
|
||||
# SAN (멀티 도메인) 확인
|
||||
openssl x509 -in nginx/ssl/train-kamco.com.crt -text -noout | grep -A1 "Subject Alternative Name"
|
||||
|
||||
# 예상 결과:
|
||||
# X509v3 Subject Alternative Name:
|
||||
# DNS:api.train-kamco.com, DNS:train-kamco.com
|
||||
```
|
||||
|
||||
## 트러블슈팅
|
||||
|
||||
### 문제 1: "Connection refused"
|
||||
|
||||
**원인**: 컨테이너가 실행되지 않음
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# 컨테이너 상태 확인
|
||||
docker ps -a | grep kamco-cd
|
||||
|
||||
# 컨테이너 재시작
|
||||
docker-compose -f docker-compose-prod.yml restart
|
||||
|
||||
# 로그 확인
|
||||
docker logs kamco-cd-nginx
|
||||
docker logs kamco-cd-training-api
|
||||
```
|
||||
|
||||
### 문제 2: "502 Bad Gateway"
|
||||
|
||||
**원인**: Nginx는 실행 중이지만 API 컨테이너가 준비되지 않음
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# API 컨테이너 상태 확인
|
||||
docker logs kamco-cd-training-api
|
||||
|
||||
# API 헬스체크 (컨테이너 내부에서)
|
||||
docker exec kamco-cd-nginx wget -qO- http://kamco-changedetection-api:8080/monitor/health
|
||||
|
||||
# API 컨테이너 재시작
|
||||
docker-compose -f docker-compose-prod.yml restart kamco-changedetection-api
|
||||
```
|
||||
|
||||
### 문제 3: "Name or service not known"
|
||||
|
||||
**원인**: /etc/hosts에 도메인이 설정되지 않음
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# /etc/hosts 확인
|
||||
cat /etc/hosts | grep train-kamco
|
||||
|
||||
# 없으면 추가
|
||||
echo "127.0.0.1 api.train-kamco.com train-kamco.com" | sudo tee -a /etc/hosts
|
||||
```
|
||||
|
||||
### 문제 4: 포트 80 또는 443이 이미 사용 중
|
||||
|
||||
**원인**: 다른 프로세스가 포트를 사용 중
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# 포트 사용 확인
|
||||
sudo lsof -i :80
|
||||
sudo lsof -i :443
|
||||
|
||||
# 사용 중인 프로세스 종료 (예: httpd, nginx)
|
||||
sudo systemctl stop httpd
|
||||
sudo systemctl stop nginx
|
||||
|
||||
# Docker Compose 재시작
|
||||
docker-compose -f docker-compose-prod.yml restart
|
||||
```
|
||||
|
||||
### 문제 5: SELinux 권한 오류
|
||||
|
||||
**원인**: SELinux가 Docker 볼륨 마운트를 차단
|
||||
|
||||
**해결**:
|
||||
```bash
|
||||
# SELinux 상태 확인
|
||||
getenforce
|
||||
|
||||
# Permissive 모드로 임시 변경 (재부팅 시 초기화됨)
|
||||
sudo setenforce 0
|
||||
|
||||
# 영구 변경 (권장하지 않음)
|
||||
sudo vi /etc/selinux/config
|
||||
# SELINUX=permissive 또는 SELINUX=disabled로 변경
|
||||
```
|
||||
|
||||
## 컨테이너 관리 명령어
|
||||
|
||||
### 시작/중지/재시작
|
||||
|
||||
```bash
|
||||
# 시작
|
||||
docker-compose -f docker-compose-prod.yml up -d
|
||||
|
||||
# 중지
|
||||
docker-compose -f docker-compose-prod.yml down
|
||||
|
||||
# 재시작
|
||||
docker-compose -f docker-compose-prod.yml restart
|
||||
|
||||
# 특정 서비스만 재시작
|
||||
docker-compose -f docker-compose-prod.yml restart nginx
|
||||
docker-compose -f docker-compose-prod.yml restart kamco-changedetection-api
|
||||
```
|
||||
|
||||
### 로그 확인
|
||||
|
||||
```bash
|
||||
# 전체 로그
|
||||
docker-compose -f docker-compose-prod.yml logs
|
||||
|
||||
# 특정 서비스 로그
|
||||
docker-compose -f docker-compose-prod.yml logs nginx
|
||||
docker-compose -f docker-compose-prod.yml logs kamco-changedetection-api
|
||||
|
||||
# 실시간 로그
|
||||
docker-compose -f docker-compose-prod.yml logs -f
|
||||
|
||||
# 마지막 N줄만 보기
|
||||
docker logs kamco-cd-nginx --tail 100
|
||||
```
|
||||
|
||||
### 컨테이너 상태 확인
|
||||
|
||||
```bash
|
||||
# 실행 중인 컨테이너
|
||||
docker-compose -f docker-compose-prod.yml ps
|
||||
|
||||
# 상세 정보
|
||||
docker inspect kamco-cd-nginx
|
||||
docker inspect kamco-cd-training-api
|
||||
|
||||
# 리소스 사용량
|
||||
docker stats kamco-cd-nginx kamco-cd-training-api
|
||||
```
|
||||
|
||||
### 컨테이너 내부 접속
|
||||
|
||||
```bash
|
||||
# Nginx 컨테이너 내부 접속
|
||||
docker exec -it kamco-cd-nginx sh
|
||||
|
||||
# API 컨테이너 내부 접속
|
||||
docker exec -it kamco-cd-training-api sh
|
||||
|
||||
# 내부에서 빠져나오기
|
||||
exit
|
||||
```
|
||||
|
||||
## 업데이트 및 재배포
|
||||
|
||||
### 코드 업데이트 후 재배포
|
||||
|
||||
```bash
|
||||
# 1. Git pull (코드 업데이트)
|
||||
git pull origin develop
|
||||
|
||||
# 2. JAR 파일 빌드 (Jenkins에서 수행하는 경우 생략)
|
||||
./gradlew clean build -x test
|
||||
|
||||
# 3. 컨테이너 재빌드 및 재시작
|
||||
docker-compose -f docker-compose-prod.yml down
|
||||
docker-compose -f docker-compose-prod.yml up -d --build
|
||||
|
||||
# 4. 로그 확인
|
||||
docker-compose -f docker-compose-prod.yml logs -f
|
||||
```
|
||||
|
||||
### 설정 파일만 변경한 경우
|
||||
|
||||
```bash
|
||||
# nginx.conf 또는 docker-compose-prod.yml 변경 시
|
||||
docker-compose -f docker-compose-prod.yml down
|
||||
docker-compose -f docker-compose-prod.yml up -d
|
||||
|
||||
# 또는
|
||||
docker-compose -f docker-compose-prod.yml restart nginx
|
||||
```
|
||||
|
||||
## 모니터링
|
||||
|
||||
### 헬스체크 엔드포인트
|
||||
|
||||
```bash
|
||||
# API 헬스체크
|
||||
curl -k https://api.train-kamco.com/monitor/health
|
||||
|
||||
# 예상 결과:
|
||||
# {
|
||||
# "status": "UP",
|
||||
# "components": {
|
||||
# "db": {"status": "UP"},
|
||||
# "diskSpace": {"status": "UP"}
|
||||
# }
|
||||
# }
|
||||
```
|
||||
|
||||
### 시스템 리소스
|
||||
|
||||
```bash
|
||||
# 디스크 사용량
|
||||
df -h
|
||||
|
||||
# 메모리 사용량
|
||||
free -h
|
||||
|
||||
# Docker 이미지 및 컨테이너 용량
|
||||
docker system df
|
||||
```
|
||||
|
||||
## 보안 권장 사항
|
||||
|
||||
1. **사설 인증서**: 현재 사설 인증서를 사용 중입니다. 프로덕션 환경에서는 **Let's Encrypt** 또는 **GlobalSign** 같은 공인 인증서 사용을 권장합니다.
|
||||
|
||||
2. **방화벽**: 필요한 포트(80, 443)만 개방하고, 불필요한 포트는 차단하세요.
|
||||
|
||||
3. **정기 업데이트**: Docker 이미지와 시스템 패키지를 정기적으로 업데이트하세요.
|
||||
|
||||
4. **로그 모니터링**: 정기적으로 로그를 확인하여 비정상적인 활동을 감지하세요.
|
||||
|
||||
5. **백업**: SSL 인증서 키 파일(`train-kamco.com.key`)과 데이터베이스를 정기적으로 백업하세요.
|
||||
|
||||
## 참고 문서
|
||||
|
||||
- **SSL 인증서 설정**: [nginx/SSL_SETUP.md](nginx/SSL_SETUP.md)
|
||||
- **프로젝트 개요**: [README.md](README.md)
|
||||
- **CLAUDE.md**: [CLAUDE.md](CLAUDE.md)
|
||||
|
||||
## 지원
|
||||
|
||||
문제가 발생하면 다음을 확인하세요:
|
||||
1. 컨테이너 로그: `docker-compose -f docker-compose-prod.yml logs`
|
||||
2. 컨테이너 상태: `docker-compose -f docker-compose-prod.yml ps`
|
||||
3. /etc/hosts 설정: `cat /etc/hosts | grep train-kamco`
|
||||
4. 방화벽 상태: `sudo firewall-cmd --list-ports`
|
||||
|
||||
---
|
||||
|
||||
**배포 완료!** 🎉
|
||||
|
||||
접속 URL:
|
||||
- `https://api.train-kamco.com`
|
||||
- `https://train-kamco.com`
|
||||
Reference in New Issue
Block a user