wing-ops/prediction/image/DOCKER_USAGE.md

# wing-image-analysis Docker 사용 가이드

드론 영상 기반 유류 오염 분석 FastAPI 서버를 Docker 컨테이너로 빌드하고 실행하는 방법을 설명한다.

---

## 목차

1. [사전 요구사항](#1-사전-요구사항)
2. [빠른 시작](#2-빠른-시작)
3. [빌드 명령어](#3-빌드-명령어)
4. [실행 명령어](#4-실행-명령어)
5. [환경변수 설정](#5-환경변수-설정)
6. [볼륨 구조](#6-볼륨-구조)
7. [API 엔드포인트 사용 예시](#7-api-엔드포인트-사용-예시)
8. [로그 확인 및 디버깅](#8-로그-확인-및-디버깅)
9. [컨테이너 관리](#9-컨테이너-관리)
10. [주의사항](#10-주의사항)
11. [CPU 전용 환경 실행](#11-cpu-전용-환경-실행)

---

## 1. 사전 요구사항

| 항목 | 최소 버전 | 확인 명령어 |
|------|----------|-------------|
| Docker Engine | 24.0 이상 | `docker --version` |
| Docker Compose | 2.20 이상 | `docker compose version` |
| NVIDIA 드라이버 | 525 이상 (CUDA 12.1 지원) | `nvidia-smi` |
| nvidia-container-toolkit | 최신 | `nvidia-ctk --version` |

### nvidia-container-toolkit 설치 (Ubuntu 기준)

```bash
# GPG 키 및 저장소 추가
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

# Docker 런타임 설정 및 재시작
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
```

### GPU 동작 확인

```bash
docker run --rm --gpus all nvidia/cuda:12.1-base-ubuntu22.04 nvidia-smi
```

---

## 2. 빠른 시작

```bash
# 1. prediction/image/ 디렉토리로 이동
cd prediction/image

# 2. 환경변수 파일 준비 (필요 시)
cp .env.example .env

# 3. 빌드 + 실행 (백그라운드)
docker compose up -d --build

# 4. 서버 상태 확인
curl http://localhost:5001/docs
```

---

## 3. 빌드 명령어

### docker compose (권장)

```bash
# 이미지 빌드만 수행 (실행 안 함)
docker compose build

# 빌드 로그를 상세하게 출력
docker compose build --progress=plain

# 캐시 없이 처음부터 빌드 (의존성 변경 시)
docker compose build --no-cache
```

### docker build (단독)

```bash
# prediction/image/ 디렉토리에서 실행
docker build -t wing-image-analysis:latest .

# 빌드 태그 지정
docker build -t wing-image-analysis:1.0.0 .

# 캐시 없이 빌드
docker build --no-cache -t wing-image-analysis:latest .
```

> **참고**: 첫 빌드는 PyTorch base 이미지(약 8GB) + GDAL/Python 패키지 설치로 **30~60분** 소요될 수 있다.
> 이후 빌드는 레이어 캐시로 수 분 내 완료된다.

---

## 4. 실행 명령어

### docker compose (권장)

```bash
# 백그라운드 실행
docker compose up -d

# 빌드 후 즉시 실행
docker compose up -d --build

# 포그라운드 실행 (로그 바로 출력)
docker compose up

# 중지
docker compose down

# 중지 + 볼륨 삭제 (데이터 초기화 시)
docker compose down -v
```

### docker run (단독 — 테스트용)

```bash
docker run --rm \
  --gpus all \
  -p 5001:5001 \
  --env-file .env \
  -v "$(pwd)/mx15hdi/Metadata/Image/Original_Images:/app/mx15hdi/Metadata/Image/Original_Images" \
  wing-image-analysis:latest
```

---

## 5. 환경변수 설정

`.env.example`을 복사하여 `.env`를 생성한다.

```bash
cp .env.example .env
```

| 변수 | 설명 | 기본값 |
|------|------|--------|
| `API_HOST` | 서버 바인드 주소 | `0.0.0.0` |
| `API_PORT` | 서버 포트 | `5001` |

---

## 6. 볼륨 구조

컨테이너 내부 경로와 호스트 경로의 매핑이다. 이미지/결과 데이터는 컨테이너 외부에 저장되어 컨테이너를 재시작해도 유지된다.

```
호스트 (prediction/image/)                     컨테이너 (/app/)
─────────────────────────────────────────────────────────────────────
mx15hdi/Metadata/Image/Original_Images/   →   mx15hdi/Metadata/Image/Original_Images/   ← 원본 이미지 입력
mx15hdi/Metadata/CSV/                     →   mx15hdi/Metadata/CSV/                     ← 메타데이터 출력
mx15hdi/Georeference/Tif/                 →   mx15hdi/Georeference/Tif/                 ← GeoTIFF 출력
mx15hdi/Georeference/Mask_Tif/            →   mx15hdi/Georeference/Mask_Tif/            ← 마스크 GeoTIFF
mx15hdi/Polygon/Shp/                      →   mx15hdi/Polygon/Shp/                      ← Shapefile 출력
mx15hdi/Detect/result/                    →   mx15hdi/Detect/result/                    ← 블렌딩 결과
mx15hdi/Detect/Mask_result/               →   mx15hdi/Detect/Mask_result/               ← 마스크 결과
starsafire/Metadata/Image/Original_Images →   starsafire/Metadata/Image/Original_Images ← 열화상 입력
starsafire/{기타}/                         →   starsafire/{기타}/                         ← 열화상 출력
stitch/                                   →   stitch/                                   ← 스티칭 결과
```

---

## 7. API 엔드포인트 사용 예시

서버 기동 후 `http://localhost:5001/docs`에서 Swagger UI로 전체 API를 확인할 수 있다.

### 7.1 전체 분석 파이프라인 실행

```bash
curl -X POST http://localhost:5001/run-script/ \
  -F "files=@/path/to/drone_image.jpg" \
  -F "camTy=mx15hdi" \
  -F "fileId=20240310_001"
```

**응답 예시**:
```json
{
  "meta": "drone_image.jpg,37,30,0,126,55,0,...",
  "data": [
    {
      "classId": 2,
      "area": 1234.56,
      "volume": 0.1234,
      "note": "갈색",
      "thickness": 0.0001,
      "wkt": "POLYGON((...))"
    }
  ]
}
```

### 7.2 메타데이터 조회

```bash
curl http://localhost:5001/get-metadata/mx15hdi/20240310_001
```

### 7.3 원본 이미지 조회 (Base64)

```bash
curl http://localhost:5001/get-original-image/mx15hdi/20240310_001
```

### 7.4 GeoTIFF + 좌표 조회

```bash
curl http://localhost:5001/get-image/mx15hdi/20240310_001
```

### 7.5 이미지 스티칭

```bash
curl -X POST http://localhost:5001/stitch \
  -F "files=@photo1.jpg" \
  -F "files=@photo2.jpg" \
  -F "mode=drone"
```

---

## 8. 로그 확인 및 디버깅

```bash
# 실시간 로그 출력
docker logs wing-image-analysis -f

# 최근 100줄만 출력
docker logs wing-image-analysis --tail 100

# 컨테이너 내부 쉘 접속
docker exec -it wing-image-analysis bash

# GPU 사용 현황 확인 (컨테이너 내부)
docker exec wing-image-analysis nvidia-smi

# Python 패키지 목록 확인
docker exec wing-image-analysis pip list
```

---

## 9. 컨테이너 관리

```bash
# 상태 확인
docker compose ps

# 재시작
docker compose restart

# 중지 (볼륨 유지)
docker compose down

# 이미지 삭제
docker rmi wing-image-analysis:latest

# 사용하지 않는 리소스 정리
docker system prune -f
```

---

## 10. 주의사항

### GPU 자동 감지
- 서버 기동 시 `torch.cuda.is_available()`로 GPU 유무를 자동 감지한다.
- GPU가 있으면 `cuda:0`, 없으면 `cpu`로 자동 폴백된다.
- 환경변수 `DEVICE`로 device를 명시 지정할 수 있다 (예: `DEVICE=cpu`, `DEVICE=cuda:1`).

### 첫 기동 시간
- AI 모델 로드: 약 **10~30초** 소요 (GPU 메모리에 로딩)
- 준비 완료 후 로그에 `Application startup complete` 메시지가 출력된다.

### workers=1 고정
- GPU 모델은 프로세스 간 공유가 불가하므로 uvicorn workers는 반드시 `1`로 유지해야 한다.
- 병렬 처리는 내부 `ThreadPoolExecutor`(max_workers=4)로 처리된다.

### 포트 충돌
- 기본 포트 `5001`이 다른 서비스와 충돌하면 `docker-compose.yml`의 `ports` 항목을 수정한다:
  ```yaml
  ports:
    - "5002:5001"  # 호스트 5002 → 컨테이너 5001
  ```

---

## 11. CPU 전용 환경 실행

GPU(NVIDIA)가 없는 환경에서는 CPU 전용 설정을 사용한다.

### 사전 요구사항 (CPU 모드)

| 항목 | 최소 버전 | 확인 명령어 |
|------|----------|-------------|
| Docker Engine | 24.0 이상 | `docker --version` |
| Docker Compose | 2.20 이상 | `docker compose version` |
| NVIDIA 드라이버 | **불필요** | — |

### 빠른 시작 (CPU)

```bash
# prediction/image/ 디렉토리로 이동
cd prediction/image

# 환경변수 파일 준비 (필요 시)
cp .env.example .env

# CPU 이미지 빌드 + 실행
docker compose -f docker-compose.cpu.yml up -d --build

# 서버 상태 확인
curl http://localhost:5001/docs
```

### 빌드 명령어 (CPU)

```bash
# CPU 이미지만 빌드
docker compose -f docker-compose.cpu.yml build

# 캐시 없이 빌드
docker compose -f docker-compose.cpu.yml build --no-cache
```

> **참고**: CPU 기반 PyTorch 이미지는 GPU 이미지(~8GB) 대비 약 70% 용량이 절감된다.
> 단, CPU 추론은 GPU 대비 처리 속도가 느리므로 대용량 이미지 분석 시 시간이 더 소요된다.

### 실행 명령어 (CPU)

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

# 포그라운드 실행 (로그 바로 출력)
docker compose -f docker-compose.cpu.yml up

# 중지
docker compose -f docker-compose.cpu.yml down
```

### 로컬 직접 실행 (Docker 없이)

```bash
# GPU 있으면 자동으로 cuda:0 사용, 없으면 cpu로 폴백
python api.py

# device 강제 지정
DEVICE=cpu python api.py
DEVICE=cuda:1 python api.py
```

### GPU/CPU 모드 확인

서버 기동 로그에서 사용 device를 확인할 수 있다:

```
[Inference] 사용 device: cpu      ← CPU 모드
[Inference] 사용 device: cuda:0   ← GPU 모드
```