Netlify에 Django를 배포한다고요? 실제로 일어나는 일들

Netlify에 Django를 배포할 수는 있습니다. 하지만 앱을 만드는 시간보다 Netlify의 제약 사항을 해결하는 데 더 많은 시간을 쓰게 될 것이며, 데모 단계를 넘어가는 순간 Django의 유용함을 만들어내는 대부분의 기능이 망가지거나 예측 불가능하게 동작할 것입니다.

Django는 완전한 서버 사이드 프레임워크 (full server-side framework)입니다. Django는 지속적인 프로세스 (persistent process)로 실행되며, 데이터베이스 연결을 유지하고, 세션 (sessions)을 처리하며, 관리자 패널 (admin panel)을 제공하고, 모든 요청에 대해 미들웨어 (middleware)를 실행합니다. 반면 Netlify는 정적 파일 (static files)을 제공하고 수명이 짧은 서버리스 함수 (serverless functions)를 실행하기 위해 구축된 JAMstack 플랫폼입니다. 이 두 가지는 근본적으로 호환되지 않으며, 이 가이드는 그 호환되지 않는 부분이 정확히 어디에서 나타나는지, 그리고 대신 무엇을 해야 하는지를 설명합니다.

개발자들이 Django를 Netlify에 배포하려는 이유

표면적으로는 그 매력이 이해가 갑니다. 이미 React나 Next.js 프론트엔드를 위해 Netlify를 사용하고 있다면, Django 백엔드도 함께 호스팅하는 것이 자연스러운 선택처럼 느껴집니다. 하나의 플랫폼, 하나의 GitHub 연동, 하나의 대시보드. 무료 티어 (free tier)는 관대해 보이고, 푸시 시 배포 (deploy-on-push) 워크플로우는 깔끔합니다.

또한 Netlify는 개발자 생태계에서 가장 잘 알려진 이름 중 하나이며, 이는 아직 백엔드 전용 호스팅 요구 사항에 집중하지 않은 개발자들에게 강력한 끌림을 제공합니다. 이 정도로 인기 있는 플랫폼이라면 모든 것을 지원할 것이라는 가정이 깔려 있습니다.

하지만 그렇지 않습니다.

**_

“개발자들이 Netlify에 Flask를 배포할 때 겪는 것과 동일한 문제가 Django에도 동일한 이유로 적용됩니다: 두 프레임워크 모두 지속적인 런타임 (persistent runtime)이 필요한 서버 사이드 Python 프레임워크이지만, Netlify는 이를 제공하지 않습니다.]”
_**

Netlify의 실체 (그리고 Django가 맞지 않는 이유)

Netlify의 JAMstack 모델 작동 방식

Netlify는 JavaScript, APIs, 그리고 Markup으로 구성된 JAMstack 모델을 중심으로 구축되었습니다. 배포 시점에 프로젝트를 정적 파일 (static files)로 빌드하면, Netlify는 글로벌 CDN (Content Delivery Network)을 통해 해당 파일들을 제공합니다. 동적인 동작을 위해 Netlify는 서버리스 함수 (serverless functions)를 제공합니다. 이는 요청이 들어올 때 실행되고, 최대 10초 동안 실행된 후 종료되는 작고 상태가 없는 (stateless) 핸들러입니다. 요청 사이에는 계속 살아있는 서버가 없습니다. 지속적인 메모리 (persistent memory)도 없습니다. 각 호출 (invocation)은 처음부터 다시 시작됩니다.

이 모델은 프론트엔드 (frontends), 마케팅 사이트, 그리고 문서화 (documentation)에 매우 탁월합니다. 하지만 백엔드 프레임워크 (backend frameworks)를 위해 설계된 것은 아닙니다.

Django가 제대로 작동하기 위해 필요한 것

Django는 정반대의 방식으로 작동합니다. Django는 Gunicorn 또는 Uvicorn과 같은 서버에 의해 유지되는 지속적인 WSGI 또는 ASGI 프로세스로 실행됩니다. 요청이 들어오면, Django는 활성화된 데이터베이스 연결 풀 (database connection pool), 활성 세션 (active sessions), 미들웨어 체인 (middleware chain), 캐시 백엔드 (cache backend), 그리고 연결된 모든 서비스에 대한 완전한 접근 권한을 갖습니다. 요청 사이에도 계속 실행 상태를 유지하며, 이것이 바로 관리자 패널 (admin panel), ORM 쿼리 (ORM queries), 인증 (authentication), 그리고 백그라운드 작업 (background tasks)과 같은 기능들을 가능하게 만드는 핵심입니다.

지속적인 프로세스 (persistent process)를 제거하면 Django의 대부분은 작동을 멈춥니다.

**_

“Netlify는 백엔드를 호스팅하기 위해 만들어지지 않았습니다. 왜 Netlify가 백엔드를 전혀 호스팅할 수 없는지 이해하는 것은 Netlify에서 Django를 사용하는 것이 왜 잘못된 접근 방식인지 이해하는 시작점입니다.”
_**

Netlify에 Django를 배포하는 방법 (존재하는 두 가지 우회 방법)

개발자들이 Netlify에서 Django를 실행하기 위해 사용하는 두 가지 접근 방식이 있습니다. 두 방식 모두 데모용으로는 충분히 잘 작동합니다. 하지만 둘 다 프로덕션 (Production) 환경에서는 버티지 못합니다.

옵션 1: serverless-wsgi를 이용한 서버리스 함수 (Serverless Functions)

serverless-wsgi와 같은 WSGI 어댑터로 Django 앱을 감싸고 이를 Netlify Function으로 배포합니다. 각 HTTP 요청은 전체 Django 애플리케이션의 콜드 서버리스 호출 (Cold serverless invocation)을 트리거합니다.

설정 과정은 다음과 같습니다:

1. serverless-wsgi를 설치하고 모든 트래픽을 핸들러 (Handler)로 라우팅하도록 netlify.toml을 구성합니다.
2. Django WSGI 앱을 감싸는 functions/server.py 파일을 생성합니다.
3. Netlify 대시보드에서 DJANGO_SETTINGS_MODULE, SECRET_KEY, DATABASE_URL을 환경 변수 (Environment variables)로 설정합니다.
4. 모든 Django 의존성(Dependencies)이 포함된 requirements.txt를 추가합니다.
5. GitHub에 푸시하여 Netlify가 빌드하도록 합니다.

홈페이지에 GET 요청을 보내면 응답이 반환될 것입니다. 하지만 실제 사용 환경에서는 즉시 문제들이 나타납니다. 콜드 스타트 (Cold starts)로 인해 비활성 상태 이후 첫 번째 요청에서 2~5초의 지연 시간 (Latency)이 추가됩니다. 데이터베이스 연결 (Database connections)은 풀링 (Pooling) 없이 매 호출마다 열리고 닫힙니다. 관리자 패널 (Admin panel)은 10초 이상 걸리는 모든 폼 제출 (Form submission)에서 작동이 중단됩니다. 파일 업로드는 실패하며, 백그라운드 작업 (Background tasks)은 실행할 수 없습니다.

옵션 2: django-distill 또는 Cactus를 이용한 정적 내보내기 (Static Export)

만약 Django 프로젝트가 런타임 데이터베이스 쿼리 (Runtime database queries) 없이 주로 콘텐츠 중심이라면, django-distill 또는 구형인 Cactus 생성기를 사용하여 뷰 (Views)를 정적 HTML로 사전 렌더링 (Pre-render)한 뒤 해당 파일들을 Netlify에 배포할 수 있습니다.

이 방식은 모든 페이지가 배포 시점에 빌드될 수 있는 앱에서만 작동합니다. 뷰가 요청 시점에 데이터베이스를 쿼리하거나, 사용자를 인증하거나, Django 관리자 (Django admin)를 건드리는 순간 제외됩니다. 대부분의 실제 Django 프로젝트에서 이는 실행 가능한 프로덕션 경로가 아닙니다. 이것은 Django 애플리케이션을 호스팅하는 방법이 아니라, Django로 생성된 정적 사이트를 호스팅하는 방법입니다.

Netlify에서 Django가 프로덕션 환경에서 무너지는 지점

이것들은 Django를 단순 데모 수준을 넘어 Netlify에 배포할 때 직면하게 될 구체적인 실패 지점들입니다.

Django 관리자 패널(Admin Panel)이 작동하지 않음

관리자 패널(Admin Panel)은 지속적인 데이터베이스 연결과 요청 간의 서버 측 세션 처리(Server-side session handling)를 필요로 합니다. Netlify의 상태가 없는 서버리스 모델(Stateless serverless model)에서는 콜드 스타트(Cold starts)로 인해 페이지 로딩이 느려지고, 사소한 데이터셋 이상의 폼 제출(Form submissions)은 10초 타임아웃(Timeout)에 걸리며, 별도의 호출(Invocations) 간에 CSRF 토큰 검증이 실패할 수 있습니다. 관리자 패널은 프로덕션 환경에서 사실상 사용이 불가능합니다.

데이터베이스 연결 고갈

Django의 ORM은 각 요청마다 데이터베이스 연결을 엽니다. 전통적인 서버에서는 Gunicorn이 연결을 재사용하는 지속적인 워커(Worker) 풀을 관리합니다. 하지만 Netlify에서는 각 서버리스 호출(Serverless invocation)이 외부 데이터베이스에 새로운 연결을 열고 이를 깔끔하게 해제하지 않습니다. 중간 정도의 트래픽이 발생하면 몇 분 내에 데이터베이스의 연결 제한(Connection limit)을 모두 소진하게 되며, 연결 거부(Connection refused) 오류가 나타나기 시작할 것입니다.

Netlify에서 마이그레이션(Migrations) 실행 불가

manage.py migrate는 지속적인 서버 프로세스에서 실행되어야 하는 데이터베이스 작업입니다. Netlify의 빌드 파이프라인(Build pipeline)은 이를 위해 설계되지 않았습니다. Netlify 빌드 훅(Build hook)의 일부로 마이그레이션을 안정적으로 실행할 수 없습니다. 대부분의 개발자는 결국 매 배포 전 로컬 머신에서 수동으로 마이그레이션을 실행하게 되며, 이는 모든 CI/CD 워크플로우를 깨뜨립니다.

10초 서버리스 타임아웃

Netlify Functions는 무료 및 Pro 플랜에서 10초라는 엄격한 실행 제한(Execution limit)을 가집니다 (Enterprise 플랜에서는 26초까지 확장 가능). 무거운 ORM 작업을 수행하거나, 이메일을 보내거나, 외부 API를 호출하거나, 파일을 처리하는 모든 Django 뷰(View)는 이 한계치에 도달하게 됩니다. Celery 또는 Django Q를 통한 장시간 실행되는 백그라운드 작업(Background tasks)은 아예 실행할 수 없습니다.

이것들은 예외적인 상황이 아닙니다. 모든 프로덕션(Production) Django 애플리케이션의 일반적인 운영 조건입니다.

**_

“잘못된 인프라 계층(Infrastructure layer)을 선택하는 것은 프로덕션 배포가 실패하는 가장 흔한 이유 중 하나입니다. 프로덕션 배포가 실패하는 가장 흔한 이유와 해결 방법 확인하기”
**_

Django가 배포 플랫폼으로부터 실제로 필요로 하는 것들

Django를 위한 플랫폼을 선택하기 전에, 해당 플랫폼이 다음 사항들을 모두 제공하는지 확인하십시오:

• 지속적인 WSGI 또는 ASGI 서버. Gunicorn 또는 Uvicorn이 콜드 스타트(Cold starts) 없이 요청 사이에도 계속 실행 상태를 유지해야 합니다.
• 커넥션 풀링(Connection pooling)을 지원하며 관리형이거나 연결 가능한 PostgreSQL. 부하가 걸렸을 때 ORM이 커넥션 제한(Connection limit)을 소진하지 않아야 합니다.
• 배포 시 자동 마이그레이션(Automated migrations). manage.py migrate가 노트북에서 수동으로 실행되는 것이 아니라, 모든 배포 시 자동으로 실행되어야 합니다.
• collectstatic 처리. Django는 매 배포마다 설정된 스토리지 백엔드(Storage backend)로 정적 파일(Static files)을 수집해야 합니다.
• 환경 변수(Environment variable) 관리. 프로덕션 환경에서는 SECRET_KEY, DATABASE_URL, ALLOWED_HOSTS, DEBUG=False가 모두 올바르게 설정되어야 합니다.
• 서버리스(Serverless) 실행 제한 없음. Django 뷰(Views), 관리자 작업(Admin operations), 그리고 백그라운드 작업(Background tasks)이 안정적으로 완료되려면 10초 이상의 시간이 필요합니다.
• 미디어 파일 업로드를 위한 지속적인 파일 시스템(Filesystem) 또는 오브젝트 스토리지(Object storage).

Netlify는 이 중 어느 것도 기본적으로 제공하지 않습니다.

**_

“Render와 같이 백엔드 기능이 있는 플랫폼이 Django 배포를 처리하는 방식을 통해 실제 적절한 Django 인프라가 어떤 모습인지 알 수 있습니다.”
**_

2026년 Django를 배포하는 더 나은 방법: Kuberns

Kuberns는 AWS 기반으로 구축된 에이전트형 AI 배포 플랫폼 (agentic AI deployment platform)입니다. GitHub 저장소 (repo)를 연결하면 AI 에이전트가 프로젝트를 읽고, Django를 감지하며, 수동 설정이나 DevOps 엔지니어가 필요했을 모든 작업을 처리합니다.

다음 3단계로 배포하세요:

1단계: GitHub 저장소를 연결합니다. Kuberns에 로그인하고 GitHub 계정을 연결하세요. Django 저장소를 선택하면 끝입니다. Kuberns가 Django를 자동으로 감지합니다.

2단계: 환경 변수 (environment variables)를 설정합니다. 대시보드에서 SECRET_KEY, DATABASE_URL, ALLOWED_HOSTS, 그리고 DEBUG=False를 추가하세요. 데이터베이스가 필요한 경우, Kuberns가 관리형 PostgreSQL을 프로비저닝 (provision)하고 DATABASE_URL을 자동으로 채워줍니다.

3단계: 배포 (Deploy)를 클릭합니다. Kuberns가 collectstatic과 migrate를 실행하고, 앱을 빌드하며, 5분 이내에 라이브 HTTPS URL을 제공합니다. 그 이후에는 저장소에 푸시 (push)할 때마다 자동으로 배포됩니다.

Kuberns가 Django를 위해 자동으로 처리하는 작업들: