Gdal 과 Python FastAPI 를 섞은 docker 이미지 생성법

gdal 공식 이미지에 여러 python gis 라이브러리를 설치하고,
추가로 fastapi 를 설치하여 GIS 관련 기능을 Rest API 로 제공하는
기능을 만들게 되었습니다.

이때 Dockerfile 를 작성해서 container 를 만들었는데,
그 방법을 추후에 또 쓰기 위해서 이렇게 글로 기록해둡니다.

📁 디렉토리 구조

Dockerfile 이 위치한 디렉토리의 전반적인 구조를 먼저 보겠습니다.

• start.sh : 이건 방법(2) - venv, pip 사용 목차에서 사용됩니다.
• python_app 디렉토리
  • 이건 FastAPI (=파이썬 코드)가 모두 담긴 디렉토리입니다.
  • python_app 디렉토리 내부는 다음과 같이 생겼고
    main.py 에 FastAPI 실행코드가 있습니다.
    

🐳 Dockerfile

파이썬의 패키지를 pip 와 uv 둘 중 어떤 걸로 관리하냐에 따라
Dockerfile 작성법이 많이 다르다 보니 방법을 2가지로 나눴습니다.
방법(1), 방법(2) 중 아무거나 하나 골라서 사용하시면 됩니다.

방법(1) - uv 사용

가장 추천하는 방법입니다.
uv 가 패키지 설치 및 관리가 편하고, 명령어의 몇가지 옵션만으로도
원하는 환경을 정확히 구현시킬 수 있습니다.

FROM ghcr.io/osgeo/gdal:ubuntu-small-3.11.0

# 한글도 읽기/쓰기가 가능토록 함
ENV LANG=C.UTF-8

# Timezone 을 우리나라에 맞춤
ENV TZ=Asia/Seoul
RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime && \
	echo $TZ > /etc/timezone

# 애플리케이션 python 코드 루트 디렉토리
ENV PYTHON_APP_HOME=/python_app

# 애플리케이션이 사용하는 python 라이브러리 경로(=venv 경로)
ENV PYTHON_VENV_DIR=/python_venv

# FastApi Port
EXPOSE 8000


# uv, uvx 설치
# COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
COPY --from=ghcr.io/astral-sh/uv:0.7.8 /uv /uvx /bin/
ENV UV_COMPILE_BYTECODE=1
ENV UV_LINK_MODE=hardlink


# 라이브러리 다운로드를 위한 디렉토리 생성 및 경로이동
WORKDIR ${PYTHON_VENV_DIR}

# uv 로 디렉토리 환경 초기화 및 기본 세팅
RUN uv init --bare && \
	uv venv --system-site-packages

# 라이브러리 설치 방법(1) : 그냥 설치
RUN	uv add fastapi --extra standard && uv add pydantic setuptools
RUN	uv add numpy rasterio netCDF4 pandas python-dotenv pytz

# 라이브러리 설치 방법(2) : pyproject.toml, uv.lock 를 사용한 설치
## COPY pyproject.toml uv.lock ${PYTHON_VENV_DIR}
## RUN uv sync --frozen --no-install-project --no-dev

# venv 활성화 스크립트의 File Permission 변경
RUN chmod u+x .venv/bin/activate

# 애플리케이션 코드 복사
WORKDIR ${PYTHON_APP_HOME}
COPY python_app ${PYTHON_APP_HOME}

# fastapi 실행
ENV PATH="${PYTHON_VENV_DIR}/.venv/bin:$PATH"
CMD ["fastapi", "run", "main.py", "--host", "0.0.0.0", "--port", "8000"]

방법(2) - venv, pip 사용

개인적으로 좀 비추천합니다. 방법1에 비해서 많이 느립니다 😂
그리고 가끔 ubuntu 아카이브 사이트의 네트워크 문제로
apt-get update 가 엄청 느린 경우가 종종 발생합니다.

# GDAL 공식 이미지를 base image 로 사용
# FROM ghcr.io/osgeo/gdal:ubuntu-small-latest
FROM ghcr.io/osgeo/gdal:ubuntu-small-3.11.0

# 한글도 읽기/쓰기가 가능토록 함
ENV LANG=C.UTF-8

# Timezone 을 우리나라에 맞춤
ENV TZ=Asia/Seoul
RUN ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime && \
	echo $TZ > /etc/timezone

# 애플리케이션 python 코드 루트 디렉토리
ENV PYTHON_APP_HOME=/python_app
ENV PYTHON_VENV_DIR=/python_venv

# FastApi Port
EXPOSE 8000

# 파이썬 관련 패키지(pip, venv) 다운로드
RUN apt-get update && apt-get install -y --no-install-recommends \
	python3-pip python3.12-venv

# APT Cache 삭제 (이미지 크기를 대략 300MB 정도 줄여줌)
RUN rm -rf /var/lib/apt/lists/*

# 파이썬 venv 환경 구성을 위한 가상 디렉토리 생성
RUN mkdir $PYTHON_VENV_DIR && python3 -m venv $PYTHON_VENV_DIR/.venv

# VENV 작업을 위해 디렉토리로 이동
WORKDIR ${PYTHON_VENV_DIR}

# venv 환경에서 system-wide python 라이브러리를 공용하기 위한 설정
RUN sed -i 's/include-system-site-packages = false/include-system-site-packages = true/' \
	.venv/pyvenv.cfg

# venv 활성화 스크립트 File Permission 변경
RUN chmod u+x .venv/bin/activate

# venv 환경 기반으로 라이브러리를 설치 (본인 입맛에 맞게 변경)
RUN /bin/bash -c "source .venv/bin/activate \
&& pip install --upgrade pip \
&& pip install numpy rasterio netCDF4 pandas \
&& pip install fastapi[standard] pydantic pytz \
&& deactivate"

# 파이썬 코드 내용을 옮길 디렉토리 생성
WORKDIR ${PYTHON_APP_HOME}

# python 소스 코드 복사
COPY python_app .

# .venv 에 설치된 fastapi 명령어 사용을 위한 PATH 설정
ENV PATH="${PYTHON_VENV_DIR}/.venv/bin:$PATH"

# fastapi 명령어 실행!
CMD ["fastapi", "run", "main.py", "--host", "0.0.0.0", "--port", "8000"]

🚀 Docker build & run

docker build 예시

docker build -t gdal-fastapi .

docker run 예시

docker run --name gdal-fastapi -p 8000:8000 -d gdal-fastapi