RESTAPI_SERVER/DOCKER.md

# 🐳 Docker 실행 가이드

REST API 서버를 Docker로 실행하는 방법을 설명합니다.

## 📋 사전 요구사항

### Windows
- Docker Desktop for Windows
- WSL2 (권장)

### Linux
- Docker Engine
- Docker Compose (선택사항)

### macOS
- Docker Desktop for Mac

## 🚀 빠른 시작

### 1. Docker Compose 사용 (권장)

#### 프로덕션 모드
```bash
# 백그라운드에서 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 중지
docker-compose down
```

#### 개발 모드
```bash
# 개발 모드로 실행
docker-compose -f docker-compose.dev.yml up

# 백그라운드 실행
docker-compose -f docker-compose.dev.yml up -d
```

### 2. 스크립트 사용

#### Windows
```cmd
# 이미지 빌드
scripts\docker-build.bat

# 프로덕션 실행
scripts\docker-run.bat

# 개발 모드 실행
scripts\docker-run-dev.bat
```

#### Linux/macOS
```bash
# 실행 권한 부여 (최초 1회)
chmod +x scripts/*.sh

# 이미지 빌드
./scripts/docker-build.sh

# 프로덕션 실행
./scripts/docker-run.sh

# 개발 모드 실행
./scripts/docker-run-dev.sh
```

## 🔧 수동 Docker 명령어

### 이미지 빌드
```bash
# 기본 빌드
docker build -t restapi-server:latest .

# 캐시 없이 빌드
docker build --no-cache -t restapi-server:latest .

# 특정 스테이지까지 빌드
docker build --target production -t restapi-server:latest .
```

### 컨테이너 실행

#### 프로덕션 모드
```bash
docker run -d \
  --name restapi-server \
  --restart unless-stopped \
  -p 5577:5577 \
  -e NODE_ENV=production \
  -e DB_HOST=39.117.244.52 \
  -e DB_PORT=11521 \
  -e DB_DATABASE=XE \
  -e DB_USERNAME=wace \
  -e DB_PASSWORD=wace0909!! \
  -e PORT=5577 \
  restapi-server:latest
```

#### 개발 모드 (볼륨 마운트)
```bash
docker run -it \
  --name restapi-server-dev \
  -p 5577:5577 \
  -e NODE_ENV=development \
  -v $(pwd):/app \
  -v /app/node_modules \
  restapi-server:latest npm run dev
```

## 📊 컨테이너 관리

### 상태 확인
```bash
# 실행 중인 컨테이너 확인
docker ps

# 모든 컨테이너 확인
docker ps -a

# 컨테이너 상세 정보
docker inspect restapi-server
```

### 로그 확인
```bash
# 실시간 로그
docker logs -f restapi-server

# 최근 100줄
docker logs --tail 100 restapi-server

# 특정 시간 이후 로그
docker logs --since "2024-01-01T00:00:00" restapi-server
```

### 컨테이너 제어
```bash
# 중지
docker stop restapi-server

# 시작
docker start restapi-server

# 재시작
docker restart restapi-server

# 제거
docker rm restapi-server

# 강제 제거
docker rm -f restapi-server
```

### 컨테이너 내부 접근
```bash
# 쉘 접근
docker exec -it restapi-server /bin/sh

# 특정 명령어 실행
docker exec restapi-server node -v
```

## 🔍 헬스체크 및 모니터링

### 헬스체크 확인
```bash
# API 헬스체크
curl http://localhost:5577/api/health

# Docker 헬스체크 상태
docker inspect --format='{{.State.Health.Status}}' restapi-server
```

### 리소스 모니터링
```bash
# 실시간 리소스 사용량
docker stats restapi-server

# 컨테이너 프로세스 확인
docker top restapi-server
```

## 🗂 환경 변수

| 변수명 | 기본값 | 설명 |
|--------|--------|------|
| NODE_ENV | production | 실행 환경 |
| PORT | 9771 | 서버 포트 |
| DB_HOST | 39.117.244.52 | Oracle DB 호스트 |
| DB_PORT | 11521 | Oracle DB 포트 |
| DB_DATABASE | XE | 데이터베이스 이름 |
| DB_USERNAME | wace | DB 사용자명 |
| DB_PASSWORD | wace0909!! | DB 비밀번호 |

### 환경 변수 파일 사용
```bash
# .env 파일 생성
cat > .env << EOF
NODE_ENV=production
PORT=5577
DB_HOST=39.117.244.52
DB_PORT=11521
DB_DATABASE=XE
DB_USERNAME=wace
DB_PASSWORD=wace0909!!
EOF

# 환경 변수 파일로 실행
docker run --env-file .env -p 5577:5577 restapi-server:latest
```

## 🔧 문제 해결

### 일반적인 문제들

#### 1. Oracle Client 오류
```bash
# 컨테이너 내부에서 Oracle Client 확인
docker exec restapi-server ls -la /opt/oracle/instantclient

# 환경 변수 확인
docker exec restapi-server env | grep ORACLE
```

#### 2. 포트 충돌
```bash
# 포트 사용 확인
netstat -tulpn | grep 9771

# 다른 포트로 실행
docker run -p 9772:9771 restapi-server:latest
```

#### 3. 메모리 부족
```bash
# 메모리 제한 설정
docker run -m 512m restapi-server:latest

# 스왑 제한 설정
docker run -m 512m --memory-swap 1g restapi-server:latest
```

#### 4. 네트워크 연결 문제
```bash
# 컨테이너 네트워크 확인
docker network ls

# 컨테이너 IP 확인
docker inspect restapi-server | grep IPAddress
```

### 로그 분석
```bash
# 에러 로그만 필터링
docker logs restapi-server 2>&1 | grep -i error

# 특정 패턴 검색
docker logs restapi-server 2>&1 | grep -i "oracle\|database"
```

## 🚀 성능 최적화

### 이미지 크기 최적화
```bash
# 이미지 크기 확인
docker images restapi-server

# 레이어 분석
docker history restapi-server:latest
```

### 멀티 스테이지 빌드 활용
현재 Dockerfile은 이미 멀티 스테이지 빌드를 사용하여 최적화되어 있습니다:
- `base`: Oracle Client 설치
- `dependencies`: 프로덕션 의존성만 설치
- `dev-dependencies`: 개발 의존성 포함
- `production`: 최종 실행 이미지

### 리소스 제한
```bash
# CPU 제한
docker run --cpus="1.5" restapi-server:latest

# 메모리 제한
docker run -m 1g restapi-server:latest

# 복합 제한
docker run --cpus="1.5" -m 1g restapi-server:latest
```

## 📦 배포 전략

### 1. Blue-Green 배포
```bash
# Green 환경 실행
docker run -d --name restapi-server-green -p 9772:9771 restapi-server:latest

# 헬스체크 후 트래픽 전환
# Blue 환경 중지
docker stop restapi-server-blue
```

### 2. 롤링 업데이트 (Docker Swarm)
```bash
# Swarm 모드 초기화
docker swarm init

# 서비스 생성
docker service create --name restapi-server --replicas 3 -p 5577:5577 restapi-server:latest

# 업데이트
docker service update --image restapi-server:v2 restapi-server
```

### 3. 컨테이너 레지스트리 사용
```bash
# 이미지 태깅
docker tag restapi-server:latest your-registry.com/restapi-server:v1.0.0

# 레지스트리에 푸시
docker push your-registry.com/restapi-server:v1.0.0

# 레지스트리에서 풀
docker pull your-registry.com/restapi-server:v1.0.0
```

## 🔐 보안 고려사항

### 1. 비root 사용자 실행
Dockerfile에서 이미 비root 사용자(`restapi`)로 실행하도록 설정되어 있습니다.

### 2. 시크릿 관리
```bash
# Docker Secrets 사용 (Swarm 모드)
echo "wace0909!!" | docker secret create db_password -

# 서비스에서 시크릿 사용
docker service create --secret db_password restapi-server:latest
```

### 3. 네트워크 보안
```bash
# 커스텀 네트워크 생성
docker network create --driver bridge restapi-network

# 네트워크에 컨테이너 연결
docker run --network restapi-network restapi-server:latest
```

이제 Docker를 사용하여 윈도우와 리눅스 환경에서 REST API 서버를 쉽게 실행할 수 있습니다!