JYP Garden

FastAPI + Docker 종합 가이드 (Medium)

Properties1
tagssource, mlops, containerization, fastapi, knowledge

7 min read

FastAPI + Docker 종합 가이드 (Medium)

Source: https://medium.com/@alidu143/containerizing-fastapi-app-with-docker-a-comprehensive-guide-416521b2457c Type: Article By: Alidu Abubakari Published: 2023-06-22 Valid as of: 2026-04-26

핵심 Takeaway

  • FastAPI: 모던 고성능 Python 웹 프레임워크 (Starlette 기반 비동기 구조)
  • 강점: 자동 타입 검증, 자동 Swagger UI + ReDoc 문서 생성, OAuth2/JWT/API Key 내장 보안
  • Docker: 일관된 실행 환경으로 “내 컴퓨터에서는 잘 되는데”문제 해결 (이식성·재현성)
  • 이미지 최적화: Python slim 베이스 + .dockerignore로 불필요 파일 제외 + RUN 명령 병합 (레이어 축소)
  • 보안: 최신 베이스 이미지 사용 + 최소 권한 원칙 (non-root 사용자) + 이미지 스캔 (취약점)
  • 네트워크 격리: Docker 내부 네트워크로 서비스 간 통신, 외부 접근 제한
  • 배포 옵션: Local (Docker Desktop) → Orchestration (K8s, Docker Swarm) → Cloud (AWS ECS, Google GKE, Azure ACI)

상세 요약

FastAPI의 특징 및 장점

FastAPI란? 현대적이고 빠른 Python 웹 API 프레임워크. 비동기 입출력(I/O) 중심의 고성능 설계.

주요 강점:

특징설명
성능Starlette의 비동기 재단 → 빠른 요청 처리 + 동시성 지원
타입 힌트Python 3.7+ 타입 힌트로 자동 유효성 검증 (JSON 구조 + 데이터형 확인)
문서 생성/docs (Swagger UI) + /redoc (ReDoc) 자동 생성 (OpenAPI 기반)
보안OAuth2, API Key, JWT 토큰 내장 지원
비동기 지원async def, await 문법으로 I/O 바운드 작업 효율화
테스트TestClient로 간단한 단위 테스트

개발 생산성:

  • 보일러플레이트 코드 최소화
  • 타입 검증 + 문서화가 통합되어 있어 별도 작업 불필요

Docker의 필요성과 이점

문제: “내 컴퓨터에서는 되는데?”

  • 개발 환경(Mac/Windows) vs 프로덕션 환경(Linux) 상이
  • 의존성 버전 차이 (Python 3.9 vs 3.11, 라이브러리 버전)
  • 설정 파일, 환경변수 미처리

Docker의 해결책:

이점설명
이식성 (Portability)같은 이미지 → 어디서나 동일한 실행 환경 (OS 무관)
재현성 (Reproducibility)Dockerfile = 인프라 코드화 → git으로 버전 관리
확장성 (Scalability)여러 컨테이너 인스턴스 병렬 실행 (부하 분산)
의존성 격리호스트 시스템과 독립적 → 충돌 없음
DevOps 통합CI/CD 파이프라인에 자연스럽게 통합 (이미지 빌드 → 테스트 → 레지스트리 푸시)

프로젝트 구조

표준 FastAPI 디렉토리 구조:

fastapi-docker-project/
├── main.py                    # 진입점 (또는 app/main.py)
├── requirements.txt           # 의존성 목록
├── Dockerfile                 # 이미지 정의
├── .dockerignore              # Docker 빌드에서 제외할 파일
└── app/                        # 애플리케이션 모듈
    ├── __init__.py
    └── routes.py              # 엔드포인트 정의

Dockerfile 최적화 패턴

기본 Dockerfile:

FROM python:3.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["uvicorn", "fastapi:app", "--host", "0.0.0.0", "--port", "8080"]

최적화 1: .dockerignore 활용

__pycache__
*.pyc
.git
.gitignore
.env
.venv/
tests/
README.md

효과: 빌드 컨텍스트 크기 축소 → 빌드 속도 개선

최적화 2: RUN 명령 병합

# ❌ 나쁜 예: 3개 레이어
RUN apt-get update
RUN apt-get install -y build-essential
RUN apt-get clean
 
# ✅ 좋은 예: 1개 레이어
RUN apt-get update && \
    apt-get install -y build-essential && \
    apt-get clean

효과: 이미지 크기 축소 (중간 결과 저장 방지)

최적화 3: 베이스 이미지 선택

  • python:3.9: 전체 개발 환경 (용량 큼)
  • python:3.9-slim: 필수만 포함 (더 가벼움) ← 권장
  • python:3.9-alpine: 초소형 (호환성 문제 가능)

보안 고려사항

1. 최신 베이스 이미지 사용

FROM python:3.9-slim  # 정기 업데이트
  • 보안 패치 포함
  • 알려진 취약점 수정

2. 최소 권한 원칙 (Non-root User)

RUN useradd -m appuser
USER appuser

컨테이너가 root로 실행되지 않도록 → 보안 강화

3. 이미지 스캔 (Vulnerability Scanning)

docker scan myimage
  • 의존성의 알려진 CVE 확인
  • 위험 라이브러리 식별 및 업데이트

4. 네트워크 격리

  • Docker 내부 네트워크: 서비스 간 통신 (외부 미노출)
  • 필요한 포트만 노출 (예: 8080)

빌드 및 실행

이미지 빌드:

docker build -t fastapi-app .

컨테이너 실행:

docker run -p 8000:8000 fastapi-app
  • -p 8000:8000: 호스트 포트 8000 → 컨테이너 포트 8000

확인:

curl http://localhost:8000/docs   # Swagger UI

배포 옵션 (발전 순서)

1단계: Local

  • Docker Desktop (Mac/Windows)
  • Docker CLI (Linux)

2단계: Orchestration

  • Kubernetes (K8s): 복잡하나 강력한 관리
  • Docker Swarm: 간단한 대안

3단계: Cloud 서비스

  • AWS ECS: 관리형 컨테이너 오케스트레이션
  • Google GKE: Google Kubernetes Engine
  • Azure ACI: Azure Container Instances
  • Hugging Face Spaces: ML 모델 호스팅 (FastAPI 지원)
  • Docker Hub: 이미지 저장소 + 간단한 배포

연결되는 위키 페이지

  • containerization — 컨테이너화 개념 및 Docker 아키텍처
  • fastapi — FastAPI 프레임워크 및 특징
  • docker — Docker 도구 및 최적화 기법
  • api-design — FastAPI API 설계 패턴
  • uvicorn — ASGI 서버 (FastAPI 실행)

그래프 뷰