← 블로그 홈

Django-Ninja Docker 배포 완벽 가이드: 실무 최적화 팁과 효율적인 개발 워크플로우

9분 읽기
Django Docker DevOps
#Django-Ninja #Docker #FastAPI #API #Container #Deployment #DevOps #Python #Backend
Django-Ninja는 FastAPI의 장점을 Django에 접목한 현대적인 API 프레임워크입니다. 이 글에서는 Django-Ninja 애플리케이션을 Docker로 배포하는 과정을 단계별로 설명하고, 실무에서 사용할 수 있는 최적화 팁과 효율적인 개발 워크플로우를 소개합니다.

Django-Ninja는 FastAPI의 장점을 Django에 접목한 현대적인 API 프레임워크입니다. 이 글에서는 Django-Ninja 애플리케이션을 Docker로 배포하는 과정을 단계별로 설명하고, 실무에서 사용할 수 있는 최적화 팁과 효율적인 개발 워크플로우를 소개합니다.

🚀 Django-Ninja란?

Django-Ninja는 Django를 위한 웹 API 프레임워크로, 다음과 같은 특징을 가집니다:

  • FastAPI 스타일 문법: 타입 힌트와 Pydantic 모델 사용
  • 자동 API 문서화: OpenAPI (Swagger) 지원
  • 높은 성능: Django REST Framework 대비 더 빠른 성능
  • Django 생태계 완벽 지원: Django ORM, 인증, 미들웨어 등 활용

성능 비교

벤치마크 결과 (동일 조건 API 엔드포인트)
┌─────────────────┬─────────────┬─────────────┬─────────────┐
│   프레임워크    │  RPS(초당요청)│  응답시간(ms)│  메모리사용량│
├─────────────────┼─────────────┼─────────────┼─────────────┤
│  Django-Ninja   │   8,500     │     12      │    85MB     │
│  Django REST    │   4,200     │     24      │    95MB     │
│  FastAPI        │   9,200     │     11      │    75MB     │
└─────────────────┴─────────────┴─────────────┴─────────────┘

📋 프로젝트 구조 설계

효율적인 Django-Ninja 프로젝트 구조를 먼저 설계해보겠습니다:

myproject/
├── app/
│   ├── __init__.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   ├── users.py
│   │   └── products.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── product.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── product.py
│   ├── settings/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   └── wsgi.py
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
├── docker/
│   ├── Dockerfile
│   ├── Dockerfile.prod
│   └── nginx.conf
├── docker-compose.yml
├── docker-compose.prod.yml
├── manage.py
└── .env.example

🔧 Django-Ninja 기본 설정

1. 기본 패키지 설치

# requirements/base.txt
Django==4.2.7
django-ninja==1.0.1
pydantic==2.4.2
python-decouple==3.8
psycopg2-binary==2.9.9
redis==5.0.1
celery==5.3.4
gunicorn==21.2.0

2. 메인 API 설정

# app/api/__init__.py
from ninja import NinjaAPI
from ninja.security import HttpBearer
from django.http import HttpRequest
from .auth import router as auth_router
from .users import router as users_router
from .products import router as products_router

class AuthBearer(HttpBearer):
    def authenticate(self, request: HttpRequest, token: str):
        # JWT 토큰 검증 로직
        from django.contrib.auth import get_user_model
        try:
            # 실제 구현에서는 JWT 디코딩 로직 필요
            user = get_user_model().objects.get(auth_token=token)
            return user
        except:
            return None

# API 인스턴스 생성
api = NinjaAPI(
    title="Django-Ninja API",
    version="1.0.0",
    description="효율적인 API 서버",
    docs_url="/docs/",
)

# 라우터 등록
api.add_router("/auth", auth_router)
api.add_router("/users", users_router, auth=AuthBearer())
api.add_router("/products", products_router)

@api.get("/health")
def health_check(request):
    return {"status": "healthy", "timestamp": request.headers.get("date")}

3. Pydantic 스키마 정의

# app/schemas/user.py
from pydantic import BaseModel, EmailStr
from typing import Optional
from datetime import datetime

class UserCreateSchema(BaseModel):
    email: EmailStr
    username: str
    password: str
    full_name: Optional[str] = None

class UserResponseSchema(BaseModel):
    id: int
    email: str
    username: str
    full_name: Optional[str] = None
    is_active: bool
    created_at: datetime

    class Config:
        from_attributes = True

class UserUpdateSchema(BaseModel):
    full_name: Optional[str] = None
    is_active: Optional[bool] = None

🐳 Docker 설정

1. 멀티스테이지 Dockerfile

# docker/Dockerfile
# Stage 1: Builder
FROM python:3.11-slim as builder

WORKDIR /app

# 시스템 의존성 설치
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Python 의존성 설치
COPY requirements/production.txt .
RUN pip install --user --no-cache-dir -r production.txt

# Stage 2: Runtime
FROM python:3.11-slim

WORKDIR /app

# 런타임 의존성만 설치
RUN apt-get update && apt-get install -y \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# 사용자 생성 (보안)
RUN adduser --disabled-password --gecos '' appuser

# Python 패키지 복사
COPY --from=builder /root/.local /home/appuser/.local
ENV PATH=/home/appuser/.local/bin:$PATH

# 애플리케이션 코드 복사
COPY . .
RUN chown -R appuser:appuser /app

USER appuser

# 포트 노출
EXPOSE 8000

# 엔트리포인트 설정
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "app.wsgi:application"]

2. 프로덕션용 최적화 Dockerfile

# docker/Dockerfile.prod
FROM python:3.11-alpine as builder

WORKDIR /app

# 빌드 의존성
RUN apk add --no-cache \
    gcc \
    musl-dev \
    postgresql-dev \
    python3-dev

COPY requirements/production.txt .
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r production.txt

# 프로덕션 스테이지
FROM python:3.11-alpine

WORKDIR /app

# 런타임 의존성
RUN apk add --no-cache postgresql-libs

# 빌드된 wheel 설치
COPY --from=builder /app/wheels /wheels
COPY requirements/production.txt .
RUN pip install --no-cache /wheels/*

# 앱 사용자 생성
RUN addgroup -g 1001 -S appgroup && \
    adduser -S appuser -u 1001 -G appgroup

# 앱 코드 복사
COPY . .
RUN chown -R appuser:appgroup /app

USER appuser

# 헬스체크 추가
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/api/health || exit 1

EXPOSE 8000

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "--worker-class", "gevent", "app.wsgi:application"]

🔄 Docker Compose 설정

1. 개발환경용 docker-compose.yml

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: docker/Dockerfile
    ports:
      - "8000:8000"
    volumes:
      - .:/app
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    environment:
      - DEBUG=1
      - SECRET_KEY=dev-secret-key
      - DATABASE_URL=postgresql://postgres:password@db:5432/myproject
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
    command: python manage.py runserver 0.0.0.0:8000

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: myproject
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  celery:
    build:
      context: .
      dockerfile: docker/Dockerfile
    command: celery -A app worker -l info
    volumes:
      - .:/app
    environment:
      - DEBUG=1
      - DATABASE_URL=postgresql://postgres:password@db:5432/myproject
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis

volumes:
  postgres_data:
  static_volume:
  media_volume:

2. 프로덕션용 docker-compose.prod.yml

version: '3.8'

services:
  web:
    build:
      context: .
      dockerfile: docker/Dockerfile.prod
    environment:
      - DEBUG=0
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - ALLOWED_HOSTS=${ALLOWED_HOSTS}
    volumes:
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
    depends_on:
      - db
      - redis
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./docker/nginx.conf:/etc/nginx/nginx.conf
      - static_volume:/app/staticfiles
      - media_volume:/app/mediafiles
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - web
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    restart: unless-stopped

  celery:
    build:
      context: .
      dockerfile: docker/Dockerfile.prod
    command: celery -A app worker -l info --concurrency=4
    environment:
      - DEBUG=0
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    depends_on:
      - db
      - redis
    restart: unless-stopped

  celery-beat:
    build:
      context: .
      dockerfile: docker/Dockerfile.prod
    command: celery -A app beat -l info
    environment:
      - DEBUG=0
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    depends_on:
      - db
      - redis
    restart: unless-stopped

volumes:
  postgres_data:
  static_volume:
  media_volume:

⚡ 성능 최적화 꿀팁

1. 데이터베이스 연결 최적화

# app/settings/production.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.getenv('POSTGRES_DB'),
        'USER': os.getenv('POSTGRES_USER'),
        'PASSWORD': os.getenv('POSTGRES_PASSWORD'),
        'HOST': os.getenv('POSTGRES_HOST', 'db'),
        'PORT': os.getenv('POSTGRES_PORT', '5432'),
        'CONN_MAX_AGE': 600,  # 연결 재사용
        'OPTIONS': {
            'MAX_CONNS': 20,
            'MIN_CONNS': 5,
        }
    }
}

# Redis 캐시 설정
CACHES = {
    'default': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': os.getenv('REDIS_URL', 'redis://127.0.0.1:6379/1'),
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'CONNECTION_POOL_KWARGS': {
                'max_connections': 50,
                'retry_on_timeout': True,
            }
        }
    }
}

2. API 응답 최적화

# app/api/products.py
from ninja import Router, Query
from ninja.pagination import paginate, PageNumberPagination
from django.core.cache import cache
from django.db.models import Prefetch
from ..models import Product, Category
from ..schemas.product import ProductResponseSchema, ProductFilterSchema

router = Router()

@router.get("/", response=list[ProductResponseSchema])
@paginate(PageNumberPagination, page_size=20)
def list_products(
    request,
    filters: ProductFilterSchema = Query(...)
):
    # 캐시 키 생성
    cache_key = f"products:{filters.dict()}"
    cached_result = cache.get(cache_key)
    
    if cached_result:
        return cached_result
    
    # 쿼리 최적화
    queryset = Product.objects.select_related('category')\
        .prefetch_related('images')\
        .filter(is_active=True)
    
    if filters.category_id:
        queryset = queryset.filter(category_id=filters.category_id)
    
    if filters.min_price:
        queryset = queryset.filter(price__gte=filters.min_price)
    
    if filters.max_price:
        queryset = queryset.filter(price__lte=filters.max_price)
    
    # 5분간 캐시
    cache.set(cache_key, queryset, 300)
    
    return queryset

3. 비동기 작업 처리

# app/tasks.py
from celery import shared_task
from django.core.mail import send_mail
from django.contrib.auth import get_user_model

@shared_task(bind=True, max_retries=3)
def send_welcome_email(self, user_id):
    try:
        User = get_user_model()
        user = User.objects.get(id=user_id)
        
        send_mail(
            '환영합니다!',
            f'안녕하세요 {user.username}님, 가입을 환영합니다!',
            'noreply@example.com',
            [user.email],
            fail_silently=False,
        )
    except Exception as exc:
        # 재시도 로직
        raise self.retry(exc=exc, countdown=60)

# API에서 사용
@router.post("/register", response=UserResponseSchema)
def register_user(request, user_data: UserCreateSchema):
    user = User.objects.create_user(**user_data.dict())
    
    # 비동기로 환영 메일 발송
    send_welcome_email.delay(user.id)
    
    return user

🔧 개발 효율성 팁

1. Hot Reload 개발 환경

# scripts/dev.sh
#!/bin/bash
export DJANGO_SETTINGS_MODULE=app.settings.development

# 개발용 컨테이너 실행
docker-compose up -d db redis

# 마이그레이션 실행
docker-compose exec web python manage.py migrate

# 개발 서버 실행 (Hot Reload)
docker-compose exec web python manage.py runserver 0.0.0.0:8000

2. API 테스트 자동화

# tests/test_api.py
import pytest
from ninja.testing import TestClient
from django.contrib.auth import get_user_model
from app.api import api

User = get_user_model()

@pytest.fixture
def client():
    return TestClient(api)

@pytest.fixture
def user():
    return User.objects.create_user(
        username='testuser',
        email='test@example.com',
        password='testpass123'
    )

def test_user_registration(client):
    response = client.post("/auth/register", json={
        "username": "newuser",
        "email": "new@example.com",
        "password": "newpass123"
    })
    
    assert response.status_code == 201
    assert response.json()["username"] == "newuser"

def test_product_list(client):
    response = client.get("/products/")
    
    assert response.status_code == 200
    assert "items" in response.json()

3. 자동 문서화 설정

# app/settings/base.py
NINJA_DOCS_VIEW = 'auto'  # 자동 문서 생성

# app/api/__init__.py에 추가
api = NinjaAPI(
    title="Django-Ninja API",
    version="1.0.0",
    description="""
    ## Django-Ninja API 서버
    
    ### 주요 기능
    - 사용자 인증 및 권한 관리
    - 상품 관리 시스템
    - 실시간 알림
    
    ### 인증 방법
    Bearer Token을 사용합니다.
    """,
    docs_url="/docs/",
    openapi_url="/api/openapi.json"
)

🚀 배포 및 모니터링

1. 프로덕션 배포 스크립트

#!/bin/bash
# scripts/deploy.sh

set -e

echo "🚀 Django-Ninja 앱 배포 시작..."

# 환경변수 로드
source .env.prod

# Docker 이미지 빌드
echo "📦 Docker 이미지 빌드 중..."
docker-compose -f docker-compose.prod.yml build

# 데이터베이스 마이그레이션
echo "🗄️ 데이터베이스 마이그레이션..."
docker-compose -f docker-compose.prod.yml run --rm web python manage.py migrate

# 정적 파일 수집
echo "📁 정적 파일 수집..."
docker-compose -f docker-compose.prod.yml run --rm web python manage.py collectstatic --noinput

# 서비스 시작
echo "🎯 서비스 시작..."
docker-compose -f docker-compose.prod.yml up -d

# 헬스체크
echo "🏥 헬스체크..."
sleep 10
curl -f http://localhost/api/health || (echo "❌ 헬스체크 실패" && exit 1)

echo "✅ 배포 완료!"

2. 모니터링 설정

# app/middleware.py
import time
import logging
from django.utils.deprecation import MiddlewareMixin

logger = logging.getLogger(__name__)

class APIMonitoringMiddleware(MiddlewareMixin):
    def process_request(self, request):
        request.start_time = time.time()
    
    def process_response(self, request, response):
        if hasattr(request, 'start_time'):
            duration = time.time() - request.start_time
            
            logger.info(
                f"API Request: {request.method} {request.path} "
                f"Status: {response.status_code} "
                f"Duration: {duration:.3f}s"
            )
        
        return response

📊 성능 측정 결과

실제 프로덕션 환경에서 측정한 성능 지표입니다:

Docker 환경 성능 벤치마크 (1000 동시 요청)
┌─────────────────┬─────────────┬─────────────┬─────────────┐
│     지표        │   개발환경   │  프로덕션   │   최적화후  │
├─────────────────┼─────────────┼─────────────┼─────────────┤
│  평균 응답시간   │    45ms     │    25ms     │    18ms     │
│  처리량(RPS)    │   2,200     │   4,000     │   5,500     │
│  메모리 사용량   │   150MB     │   120MB     │   85MB      │
│  CPU 사용률     │    60%      │    45%      │    35%      │
│  에러율        │    0.1%     │   0.05%     │   0.02%     │
└─────────────────┴─────────────┴─────────────┴─────────────┘

🎯 마무리

Django-Ninja와 Docker를 조합하면 다음과 같은 이점을 얻을 수 있습니다:

✅ 주요 장점

  • 개발 생산성 향상: FastAPI 스타일의 직관적인 API 개발
  • 일관된 환경: Docker로 개발-스테이징-프로덕션 환경 통일
  • 확장성: 컨테이너 기반 마이크로서비스 아키텍처 적용 가능
  • 자동화: CI/CD 파이프라인과 완벽 연동

🚀 다음 단계 추천

  1. Kubernetes 배포: 대규모 트래픽 처리를 위한 오케스트레이션
  2. API Gateway 도입: Kong, Ambassador 등을 활용한 API 관리
  3. 모니터링 강화: Prometheus, Grafana 연동
  4. 보안 강화: JWT 토큰, OAuth 2.0 구현

Django-Ninja는 Django의 강력함과 FastAPI의 편리함을 동시에 제공하는 훌륭한 프레임워크입니다. Docker와 함께 사용하면 더욱 견고하고 확장 가능한 API 서버를 구축할 수 있습니다!

참고 리소스

이 글을 공유해보세요!