# 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`