wing-ops/prediction/image/DOCKER_USAGE.md

wing-image-analysis Docker 사용 가이드

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

---

목차

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

---

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 기준)

# 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 동작 확인

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

---

2. 빠른 시작

# 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 (권장)

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

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

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

docker build (단독)

# 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 (권장)

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

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

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

# 중지
docker compose down

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

docker run (단독 — 테스트용)

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를 생성한다.

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 전체 분석 파이프라인 실행

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

응답 예시:

{
  "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 메타데이터 조회

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

7.3 원본 이미지 조회 (Base64)

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

7.4 GeoTIFF + 좌표 조회

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

7.5 이미지 스티칭

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

---

8. 로그 확인 및 디버깅

# 실시간 로그 출력
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. 컨테이너 관리

# 상태 확인
docker compose ps

# 재시작
docker compose restart

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

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

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

---

10. 주의사항

GPU 필수

• AI 모델(epoch_165.pth)은 cuda:0 디바이스로 로드된다.
• GPU 없이 실행하면 서버 기동 시 오류가 발생한다.
• CPU 전용 환경에서 테스트하려면 Inference.py의 device='cuda:0'을 device='cpu'로 수정해야 한다.

첫 기동 시간

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

workers=1 고정

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

포트 충돌

• 기본 포트 5001이 다른 서비스와 충돌하면 docker-compose.yml의 ports 항목을 수정한다:

  ports:
    - "5002:5001"  # 호스트 5002 → 컨테이너 5001