500부터 모듈, .env까지 한 번에 정리하는 Django Deployment Error 해결 가이드 5편

Django Deployment Error 에러 해결 이미지

“Django Deployment Error 해결”은 결국 로그랑 친해지는 과정

배포를 해보면 알게 됩니다.
진짜 프로젝트는 항상 에러와 함께 올라가요.

  • 500 Internal Server Error
  • ModuleNotFoundError: No module named ...
  • .env 한글 때문에 터지는 UnicodeEncodeError

studymate.secondlife.lol를 올리는 동안,
저도 이 모든 걸 다 겪으면서 “아, 이게 진짜 장고 배포 에러 해결이구나…” 하고 체감했습니다.

이번 5편에서는

Studymate를 배포하면서 실제로 겪었던 에러들을 중심으로
Django Deployment Error 해결 패턴을 한 번 정리해 보려고 합니다.

“에러 날 때마다 새로 검색하는” 단계에서
“아, 이건 이쪽 문제겠구나.” 하고 감이 오는 수준까지 가는 게 목표입니다.

이런 상황에서 꼭 필요한 “Django Deployment Error 해결”

1. 도메인까지 연결했는데 500만 보일 때

  • 도메인: OK
  • Python 3.12 venv: OK
  • manage.py runserver: OK

그런데 외부에서 접속하면 500 Internal Server Error만 딱 뜰 때,
이건 무조건 장고 배포 에러 해결 모드로 들어가야 합니다.

이때 중요한 건

  • “코드 잘 돌아가는데 왜 500이야?”라는 분노가 아니라
  • stderr.log, Apache 로그, manage.py check 를 차분히 보는 습관

즉, 진짜 장고 배포 에러 해결의 출발점은 “로그와 친해지기”예요.

2. 패키지 설치는 한 듯한데, ModuleNotFoundError가 계속 나올 때

jazzmin, allauth, rest_framework…

로컬에서는 잘 됐는데 서버에서는

ModuleNotFoundError: No module named 'jazzmin'
ModuleNotFoundError: No module named 'allauth'

이런 메시지가 보이면,
장고 배포 에러 해결의 관점에서 제일 먼저 봐야 할 건:

  • “지금 내가 보고 있는 venv가 맞는가?”
  • “Setup Python App가 쓰는 venv에 설치했는가?”

입니다. 같은 패키지인데 venv가 다르면 없는 거나 마찬가지니까요.

3. .env 설정은 잘 한 것 같은데, 이유를 알 수 없는 500이 날 때

SECRET_KEY, ALLOWED_HOSTS, DATABASE_URL까지 잘 넣은 것 같은데,
Setup Python App으로 돌리면 500이 뜨고,
로그를 보면 난데없이 UnicodeEncodeError가 튀어나올 때…

이건 좀 더 고급 단계의 Django Deployment Error 해결 영역이죠.
환경에 따라 기본 인코딩이 ASCII일 수 있다는 걸 실제로 겪어봐야
“.env 값에 한글 넣지 말자”라는 교훈이 몸에 새겨집니다.

유형별로 정리하는 장고 배포 에러 해결 패턴

이제 실제로 겪었던 에러들을 유형별로 묶어서
장고 배포 에러 해결 체크리스트처럼 정리해볼게요.

1. 500 Internal Server Error – 첫 번째 관문

500 Internal Server Error image

증상

  • 브라우저: 500 Internal Server Error
  • 화면엔 정보 거의 없음
  • 장고 디버그 화면도 안 보임 (DEBUG=False)

Django Deployment Error 해결 포인트

  1. python manage.py check 먼저 실행source /home2/계정명/virtualenv/studymate_project/3.12/bin/activate cd /home2/계정명/studymate_projectDJANGO_SETTINGS_MODULE=config.settings.prod python manage.py check
    • 여기서 에러가 나면, WSGI 이전에 설정 자체 문제
    • 여기서 OK면, WSGI/Passenger/.env 쪽 문제일 가능성 ↑
  2. stderr.log tail 해서 마지막 40줄 확인cd /home2/계정명/studymate_project tail -n 40 stderr.log 여기서 진짜 장고 배포 에러 해결의 힌트가 나옵니다.
    • settings import 에러ModuleNotFoundErrorUnicodeEncodeErrorSyntaxError
    등등, 500 참고인들이 줄줄이 찍혀 있어요.
  3. 수정 후에는 Setup Python App에서 꼭 Restart장고 배포 에러 해결 과정에서 설정을 고쳤다면,
    cPanel → Setup Python App → 앱 선택 → Restart 버튼은 습관처럼 눌러주기.

2. ModuleNotFoundError – venv/requirements 문제

증상 예시

ModuleNotFoundError: No module named 'jazzmin'
ModuleNotFoundError: No module named 'allauth'

로컬에서는 잘 되는데 서버에서만 나오는 대표적인 장고 배포 에러 해결 케이스입니다.

Django Deployment Error 해결 포인트

  1. 지금 VENV가 맞는지 확인which python python --version
    • 경로가 /home2/계정명/virtualenv/studymate_project/3.12/bin/python 이라면 OK
    • /usr/bin/python3 같은 시스템 Python이면, 잘못된 venv에서 설치 중일 수 있음
  2. 필요 패키지 설치
    • pip install django-jazzmin pip install django-allauth # 또는 pip install -r requirements.txt
  3. INSTALLED_APPS와 패키지 이름 매칭 확인
    • 패키지: django-jazzmin → 모듈: jazzmin
    • 패키지: django-allauth → 모듈: allauth
  4. 다시 python manage.py check → Restart → 브라우저 확인

이 과정을 반복하다 보면,
패키지 관련 장고 배포 에러 해결은 금방 루틴화됩니다.

3. .env 인코딩 이슈 – UnicodeEncodeError

UnicodeEncodeError image

실제 에러 메시지 패턴

UnicodeEncodeError: 'ascii' codec can't encode characters in position ...
  File ".../dotenv/main.py", line 111, in set_as_environment_variables
    os.environ[k] = v

장고 배포 에러 해결 중에서 가장 “어, 이게 왜?” 했던 케이스입니다.

원인

  • .env 값에 한글이 들어있고
  • 서버(케미클라우드) 환경이 ASCII 기반 로케일이라
  • os.environ에 세팅할 때 인코딩 에러 발생

예를 들어

SECRET_KEY=여기에_운영용_시크릿키_작성  # ❌

이렇게 한글이 들어가면 바로 문제 발생.

장고 배포 에러 해결 방법

  1. .env 값을 전부 ASCII로 변경
    • SECRET_KEY=django-insecure-랜덤영문숫자기호 # 영어/숫자/기호만
    • DEBUG=False
    • ALLOWED_HOSTS=secondlife.lol,studymate.secondlife.lol
  2. 설명은 모두 주석으로 분리
    • # 서비스 이름: 스터디메이트(Studymate) SERVICE_NAME=Studymate
  3. 다시 python manage.py check → Restart → 브라우저 확인

이 이후로는 .env 작성할 때
“값에는 한글 금지, 설명은 전부 주석”이라는 규칙을 자동으로 떠올리는 수준이 됩니다.
그게 바로 몸으로 배우는 장고 배포 에러 해결이죠.

4. passenger_wsgi.py 재귀 이슈 – load_source 지옥

증상

로그에 이런 패턴이 무한 반복

File "passenger_wsgi.py", line 16, in <module>
    wsgi = load_source('wsgi', 'passenger_wsgi.py')
...

케미클라우드가 기본으로 생성해준 passenger_wsgi.py를
그대로 썼다가 생긴 문제였어요.

Django Deployment Error 해결 방법

템플릿을 지우고, 최소한의 WSGI 코드로 덮어쓰기

import os
import sys
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent

if str(BASE_DIR) not in sys.path:
    sys.path.insert(0, str(BASE_DIR))

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings.prod")

from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

이렇게 바꾸고 나서야,
Setup Python App이 장고를 제대로 띄워주기 시작했습니다.
이것도 기억해두면 좋은 장고 배포 에러 해결 패턴 중 하나입니다.

5. 정리용 미니 체크리스트 – 장고 배포 에러 해결 루틴

마지막으로, 앞으로도 써먹을 수 있는
장고 배포 에러 해결 체크리스트를 짧게 정리해 볼게요.

  1. CLI에서 먼저 확인
    • DJANGO_SETTINGS_MODULE=config.settings.prod python manage.py check
  2. 로그 확인
    • tail -n 40 stderr.log (혹은 ChemiCloud Error Logs)
  3. 패키지 문제면
    • venv 확인 → pip install ... → 다시 check
  4. .env 문제면
    • 값에 한글 제거 → ASCII만 사용 → 주석에 한글
  5. WSGI 문제면
    • passenger_wsgi.py 최소 버전으로 정리
  6. 수정 후에는
    • Setup Python App → Restart → 브라우저 새로고침

이 6단계만 습관처럼 돌려도,
앞으로 만날 대부분의 장고 배포 에러 해결은
“겁나는 일 → 귀찮지만 할 수 있는 일” 정도로 바뀔 거예요.

유사한 게시물