9.1 KiB
9.1 KiB
KAMCO Training API 배포 가이드 (RedHat 9.6)
빠른 배포 (Quick Start)
이 문서는 RedHat 9.6 환경에서 HTTPS로 KAMCO Training API를 배포하는 방법을 설명합니다.
접속 URL:
https://api.train-kamco.comhttps://train-kamco.com
사전 요구사항
- Docker & Docker Compose 설치
- Git 설치
- sudo 권한
- 포트 80, 443 사용 가능
1단계: /etc/hosts 설정
# 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단계: 방화벽 설정 (필요시)
# 방화벽 상태 확인
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단계: 프로젝트 디렉토리로 이동
cd /path/to/kamco-train-api
# 현재 위치 확인
pwd
# 예상: /home/username/kamco-train-api
4단계: 파일 구조 확인
배포 전 필수 파일이 모두 있는지 확인하세요:
# SSL 인증서 확인
ls -la nginx/ssl/
# 예상 결과:
# train-kamco.com.crt (인증서)
# train-kamco.com.key (개인 키)
# openssl.cnf (설정 파일)
# Docker Compose 파일 확인
ls -la docker-compose-prod.yml nginx/nginx.conf
# 예상: 두 파일 모두 존재
5단계: Docker 네트워크 생성 (최초 1회)
# kamco-cds 네트워크가 있는지 확인
docker network ls | grep kamco-cds
# 없으면 생성
docker network create kamco-cds
6단계: Docker Compose 배포
# 기존 컨테이너 중지 (있는 경우)
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단계: 배포 확인
컨테이너 로그 확인
# 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 리다이렉트 테스트
# 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 헬스체크
# -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/healthhttps://train-kamco.com/monitor/health
사설 인증서 경고:
- "안전하지 않음" 경고가 표시되면 "고급" → "계속 진행" 클릭
8단계: SSL 인증서 확인 (선택사항)
# 인증서 정보 확인
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"
원인: 컨테이너가 실행되지 않음
해결:
# 컨테이너 상태 확인
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 컨테이너가 준비되지 않음
해결:
# 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에 도메인이 설정되지 않음
해결:
# /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이 이미 사용 중
원인: 다른 프로세스가 포트를 사용 중
해결:
# 포트 사용 확인
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 볼륨 마운트를 차단
해결:
# SELinux 상태 확인
getenforce
# Permissive 모드로 임시 변경 (재부팅 시 초기화됨)
sudo setenforce 0
# 영구 변경 (권장하지 않음)
sudo vi /etc/selinux/config
# SELINUX=permissive 또는 SELINUX=disabled로 변경
컨테이너 관리 명령어
시작/중지/재시작
# 시작
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
로그 확인
# 전체 로그
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
컨테이너 상태 확인
# 실행 중인 컨테이너
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
컨테이너 내부 접속
# Nginx 컨테이너 내부 접속
docker exec -it kamco-cd-nginx sh
# API 컨테이너 내부 접속
docker exec -it kamco-cd-training-api sh
# 내부에서 빠져나오기
exit
업데이트 및 재배포
코드 업데이트 후 재배포
# 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
설정 파일만 변경한 경우
# 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
모니터링
헬스체크 엔드포인트
# API 헬스체크
curl -k https://api.train-kamco.com/monitor/health
# 예상 결과:
# {
# "status": "UP",
# "components": {
# "db": {"status": "UP"},
# "diskSpace": {"status": "UP"}
# }
# }
시스템 리소스
# 디스크 사용량
df -h
# 메모리 사용량
free -h
# Docker 이미지 및 컨테이너 용량
docker system df
보안 권장 사항
-
사설 인증서: 현재 사설 인증서를 사용 중입니다. 프로덕션 환경에서는 Let's Encrypt 또는 GlobalSign 같은 공인 인증서 사용을 권장합니다.
-
방화벽: 필요한 포트(80, 443)만 개방하고, 불필요한 포트는 차단하세요.
-
정기 업데이트: Docker 이미지와 시스템 패키지를 정기적으로 업데이트하세요.
-
로그 모니터링: 정기적으로 로그를 확인하여 비정상적인 활동을 감지하세요.
-
백업: SSL 인증서 키 파일(
train-kamco.com.key)과 데이터베이스를 정기적으로 백업하세요.
참고 문서
- SSL 인증서 설정: nginx/SSL_SETUP.md
- 프로젝트 개요: README.md
- CLAUDE.md: CLAUDE.md
지원
문제가 발생하면 다음을 확인하세요:
- 컨테이너 로그:
docker-compose -f docker-compose-prod.yml logs - 컨테이너 상태:
docker-compose -f docker-compose-prod.yml ps - /etc/hosts 설정:
cat /etc/hosts | grep train-kamco - 방화벽 상태:
sudo firewall-cmd --list-ports
배포 완료! 🎉
접속 URL:
https://api.train-kamco.comhttps://train-kamco.com