Gunicorn을 사용하여 Django 배포하기

Gunicorn은 파이썬 기반 WSGI(Web Server Gateway Interface) 서버로, Django 같은 웹 애플리케이션을 프로덕션 환경에서 구동할 때 많이 사용됩니다. 공식 문서에 따르면 Gunicorn은 순수 파이썬으로 작성된 UNIX용 WSGI 서버이며, 별도 의존성이 없어 pip로 간단히 설치할 수 있습니다. Django에는 테스트용 간이 개발 서버가 내장되어 있지만, 실제 서비스 환경에서는 더 안정적이고 빠른 Gunicorn 같은 웹서버가 필요합니다.

Django 프로젝트를 Gunicorn으로 실행하기

가장 기본적인 Gunicorn 실행 방법은 gunicorn 명령에 WSGI 모듈 경로를 전달하는 것입니다. 예를 들어, Django 프로젝트의 wsgi.py 모듈이 myproject.wsgi라면, 프로젝트 디렉터리(보통 manage.py 파일이 있는 곳)에서 다음과 같이 실행합니다:

pip install gunicorn
gunicorn myproject.wsgi

이 명령은 기본적으로 127.0.0.1:8000에서 HTTP 요청을 대기합니다. 필요에 따라 포트나 호스트를 지정할 수 있으며, 다음과 같이 여러 옵션을 줄 수 있습니다:

# 0.0.0.0:8000 모든 인터페이스에서 수신, 워커 프로세스 3개 사용 예시
gunicorn --workers 3 --bind 0.0.0.0:8000 myproject.wsgi

위와 같이 실행하면 Django 개발 서버(runserver)와 비슷하게 애플리케이션이 구동되며, 브라우저에서 http://서버_IP:8000으로 접속하여 동작을 확인할 수 있습니다. (단, Gunicorn은 정적 파일 제공 기능이 없으므로, 추후 Nginx와 연동하여 정적파일을 처리해야 합니다.)

개발 환경과 운영 환경 분리하기

개발용과 운영용 설정을 분리하는 것은 매우 중요합니다. 예를 들어 개발 단계에서는 DEBUG=True로 실행하지만, 운영 환경에서는 반드시 DEBUG=False로 설정하고 적절한 ALLOWED_HOSTS를 지정해야 합니다. Django 공식 문서에서도 “DEBUG가 False로 설정된 경우 반드시 ALLOWED_HOSTS를 설정해야 한다”라고 안내하고 있습니다.

이를 위해 일반적으로 settings.py를 환경별로 분리합니다. 예를 들어 settings_dev.py, settings_prod.py 같은 파일을 만들고, 운영 서버에서는 환경변수 DJANGO_SETTINGS_MODULE을 통해 사용할 설정을 지정합니다.

export DJANGO_SETTINGS_MODULE=myproject.settings_prod

또한 비밀키나 데이터베이스 비밀번호 같은 민감 정보는 .env 파일 등에 두고 환경변수로 로드하는 방법이 널리 사용됩니다. django-environ 같은 라이브러리를 사용하면 .env 파일에서 환경변수를 읽어와 Django 설정에서 활용할 수 있습니다. 예를 들어 .env에 비밀키를 저장해두고 settings.py에서 읽으면, 코드에 직접 민감 정보가 노출되지 않아 안전합니다.

Gunicorn을 systemd 서비스로 등록하기 (Ubuntu 기준)

운영 서버에서는 SSH 접속 시마다 수동으로 Gunicorn을 실행하는 대신, systemd 서비스를 만들어 자동으로 구동하는 것이 좋습니다. 다음은 Ubuntu에서 Gunicorn 서비스를 등록하는 예시입니다.

1. 서비스 파일 생성: /etc/systemd/system/gunicorn.service 파일을 생성하고 다음과 같이 작성합니다. (<...> 부분은 실제 경로와 사용자명으로 변경하세요.)위 예시에서는 가상환경(myenv)의 Gunicorn을 사용하여 프로젝트의 WSGI 애플리케이션을 소켓(gunicorn.sock)으로 바인딩하여 실행하도록 설정했습니다. 이와 유사한 서비스 파일 구성 방법은 관련 문서에 설명되어 있습니다.
2. [Unit] Description=gunicorn daemon for Django project After=network.target [Service] User=<youruser> Group=www-data WorkingDirectory=/home/<youruser>/myproject Environment="PATH=/home/<youruser>/myproject/myenv/bin" ExecStart=/home/<youruser>/myproject/myenv/bin/gunicorn \ --workers 3 --bind unix:/run/gunicorn.sock myproject.wsgi:application [Install] WantedBy=multi-user.target
3. 서비스 활성화 및 실행: 서비스 파일을 저장한 후, systemd 데몬을 리로드하고 Gunicorn 서비스를 시작 및 부팅 시 자동 실행하도록 설정합니다.위 명령으로 서비스를 시작하면 gunicorn.socket이나 소켓 파일(/run/gunicorn.sock)이 생성되고, Gunicorn이 실행됩니다. 서비스가 정상적으로 실행되었는지 sudo systemctl status gunicorn로 확인할 수 있습니다.
4. sudo systemctl daemon-reload sudo systemctl start gunicorn sudo systemctl enable gunicorn
5. 로그 확인: 서비스가 제대로 구동되지 않으면 journalctl -u gunicorn 명령으로 로그를 확인합니다. (예: 포트 충돌, 경로 오류 등)

이제 서버를 재부팅해도 Gunicorn이 자동으로 실행되며, 필요 시 sudo systemctl stop gunicorn으로 중단할 수 있습니다.

Nginx와 연동하기 (간단히 언급)

실서비스 환경에서는 보통 Gunicorn 앞단에 Nginx를 두어 리버스 프록시로 연동합니다. Nginx는 정적 파일을 효율적으로 처리해주며, SSL 설정, 로드 밸런싱 등 다양한 기능을 제공합니다. 예를 들어 Nginx 서버 블록을 구성하여 proxy_pass http://unix:/run/gunicorn.sock;로 Gunicorn 소켓을 연결합니다. 상세 구성은 차후 포스트에서 다룰 예정입니다.

마치며

이상으로 Gunicorn을 이용하여 Django 애플리케이션을 실행하고, 운영 환경에서 systemd로 서비스를 관리하는 기본 과정을 설명했습니다. 이 과정을 통해 개발 서버 대신 안정적인 방식으로 Django 앱을 배포할 수 있습니다. 이후 Nginx와의 연동 방법을 추가로 학습하면, 더욱 완전한 배포 환경을 구성할 수 있습니다.

참고: Django 공식 문서와 다양한 튜토리얼에서 Gunicorn 설치 및 배포 방법을 안내하고 있으니, 필요에 따라 공식 가이드도 참고하시기 바랍니다.