백엔드

Django 프로젝트의 settings.py 주요 설정과 활용법

지식소 채움이 2025. 6. 4. 22:19

Django 프로젝트의 settings.py 파일은 프로젝트의 전반적인 설정을 정의하는 핵심 파일입니다. 처음에는 내용이 방대하고 어려워 보일 수 있지만, 알고 보면 단순히 Django 프로젝트의 다양한 설정 값을 모아놓은 파이썬 파일일 뿐입니다. 이번 포스트에서는 settings.py의 전체 구조와 주요 설정 항목들을 알아보고, 개발/배포 환경에 따라 설정을 분리 및 관리하는 방법까지 살펴보겠습니다. 이를 통해 Django 입문자가 settings.py를 자신 있게 다룰 수 있도록 돕는 것이 목표입니다.

settings.py의 구조 개요

Django의 기본 settings.py는 여러 섹션으로 구성되어 있습니다. 먼저 프로젝트의 루트 경로를 나타내는 BASE_DIR 설정이 정의되며, 이후 보안/디버그, 애플리케이션, 미들웨어, 데이터베이스, 정적 파일 등으로 주제별 설정 값들이 이어집니다. 주요 섹션을 간략히 살펴보면 다음과 같습니다:

  1. 프로젝트 경로 설정 – BASE_DIR 등으로 프로젝트의 루트 디렉터리 경로를 지정 (다른 경로 설정의 기준이 됨). 예를 들어 아래와 같이 정의됩니다:이 BASE_DIR을 통해 프로젝트 파일 경로를 일관되게 참조할 수 있습니다 (예: BASE_DIR / "db.sqlite3"는 프로젝트 루트에 DB 파일 생성).
  2. from pathlib import Path BASE_DIR = Path(__file__).resolve().parent.parent
  3. 보안 및 디버그 설정 – SECRET_KEY, DEBUG, ALLOWED_HOSTS 등을 정의합니다. SECRET_KEY는 Django의 보안에 매우 중요한 비밀 키로, 세션 데이터 서명이나 CSRF 토큰 등에 사용되므로 절대로 외부에 노출되면 안 됩니다. DEBUG 모드는 디버그 페이지 표시 여부를 결정하고, ALLOWED_HOSTS는 허용할 호스트 도메인을 지정합니다.
  4. 애플리케이션 설정 – INSTALLED_APPS로 사용 중인 Django 내장 앱들과 개발자가 만든 앱들을 등록합니다. 이 목록에 포함되지 않은 앱은 Django에서 동작하지 않으므로, 새로운 앱을 만들면 반드시 여기에 추가해야 합니다.
  5. 미들웨어 설정 – MIDDLEWARE 리스트로 요청/응답 처리 과정에 적용할 미들웨어 클래스를 나열합니다. 보안, 세션, 인증 등 다양한 기능의 미들웨어를 순서대로 등록합니다.
  6. 기타 설정 – 이 밖에도 ROOT_URLCONF(프로젝트 URL 라우팅), WSGI_APPLICATION(WSGI 인터페이스), DATABASES(데이터베이스 연결 정보), AUTH_PASSWORD_VALIDATORS(비밀번호 검증 규칙), LANGUAGE_CODE/TIME_ZONE(국제화 및 시간대), STATIC_URL/MEDIA_URL(정적/미디어 파일 경로) 등 여러 항목이 있습니다. 이들 설정을 적절히 조정하면 Django 프로젝트를 더욱 안전하고 효율적으로 운영할 수 있습니다.

이제 특히 초보자가 꼭 알아야 할 주요 설정 항목들을 하나씩 살펴보겠습니다. 각 항목의 역할과 예시 코드를 통해 이해를 도와드리겠습니다.

주요 설정 항목 살펴보기

DEBUG (디버그 모드)

DEBUG 는 장고의 디버그 모드 활성화 여부를 나타내는 불리언 값입니다. 기본값은 True이며, 개발 단계에서 편의를 위해 상세한 에러 트레이스백과 디버그 정보를 브라우저에 표시해줍니다. 예를 들어 개발 중 오류가 발생하면 브라우저에서 구체적인 오류 원인과 디버그 정보를 확인할 수 있습니다. 반면 운영 환경에서는 반드시 DEBUG = False로 설정해야 합니다. DEBUG=False일 경우 Django는 자세한 오류 대신 사용자에게 친화적인 에러 페이지만 보여주고, 내부적으로 민감한 디버그 정보를 노출하지 않습니다.

DEBUG = True  # 개발 환경에서는 True, 배포(운영) 환경에서는 False로 설정
  • DEBUG=True (개발용): 장고의 상세한 오류 페이지 활성화, 정적 파일을 개발 서버가 직접 서빙, 보안 검사 일부 완화. 개발 중에는 편리하지만, 보안상 안전하지 않으므로 실제 서비스에서는 사용하지 않습니다.
  • DEBUG=False (운영용): 상세 오류 내용이 공개되지 않고 로그에만 기록됩니다. 개발용 서버에서는 정적 파일을 자동 제공하지 않으며, 별도의 설정이 필요합니다. 무엇보다 보안을 위해 DEBUG를 꺼야 하며, 잘못된 설정 노출을 방지할 수 있습니다.

💡 주의: DEBUG=False로 설정할 경우 반드시 아래의 ALLOWED_HOSTS도 올바르게 지정해야 합니다. 그렇지 않으면 Django는 모든 요청을 “Bad Request (400)”로 응답하며 외부 접근을 차단합니다.

ALLOWED_HOSTS (허용할 호스트)

ALLOWED_HOSTS 는 해당 Django 사이트가 응답할 수 있는 호스트/도메인 이름의 목록입니다. 즉, 웹 브라우저의 요청 Host 헤더와 대조하여, 여기에 포함된 호스트에 대해서만 장고 앱이 서비스를 제공하도록 제한합니다. 이 설정은 HTTP Host 헤더 공격을 방지하기 위한 보안 조치입니다. 기본값은 빈 리스트([])이며, DEBUG=True 상태에서 빈 값이면 장고가 자동으로 localhost, 127.0.0.1 등을 허용하도록 예외 처리합니다. 그러나 운영 환경에서는 DEBUG를 끄는 동시에 ALLOWED_HOSTS에 실제 서비스 도메인을 명시해야 외부 요청이 정상 처리됩니다. 모든 호스트를 허용하려면 ['*']로 설정할 수도 있지만, 권장되지는 않습니다 (보안상 취약해질 수 있음).

ALLOWED_HOSTS = ['127.0.0.1', 'localhost', 'mywebsite.com']  # 허용할 도메인 목록

위 예시처럼 개발 단계에서는 로컬호스트와 테스트용 도메인을, 운영 단계에서는 실제 서비스 도메인을 지정합니다. 만약 운영 환경에서 이 값을 비워두면 Django는 외부 요청을 모두 거부하므로 꼭 설정해야 합니다.

INSTALLED_APPS (설치된 앱 목록)

INSTALLED_APPS는 현재 Django 프로젝트에서 활성화할 앱들의 리스트입니다. 문자열로 앱의 경로를 지정하며, 장고 기본 제공 앱들과 사용자 정의 앱들을 모두 포함합니다. 이 목록에 없는 앱은 장고에서 로드되거나 동작하지 않으므로, 새로운 앱을 생성했을 경우 반드시 여기 추가해야 합니다. 기본 프로젝트 생성 시에는 관리자(admin), 인증(auth), 세션(sessions), 메시지(messages), 정적 파일(staticfiles) 관련 기본 앱들이 나열되어 있습니다.

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "myapp",  # 내가 만든 앱 등록 (예시)
]

위 예시에서는 Django 기본 앱들과 함께 사용자 정의 앱인 "myapp"을 등록했습니다. INSTALLED_APPS에 등록되지 않은 앱의 기능은 장고가 인지하지 못하므로 동작하지 않습니다. 따라서 REST framework나 Django Extensions 같은 서드파티 패키지를 설치한 경우에도 여기에 추가해 주어야 합니다.

MIDDLEWARE (미들웨어 설정)

MIDDLEWARE는 요청과 응답의 처리 과정에 적용될 미들웨어 클래스들의 리스트입니다. 미들웨어는 장고 요청/응답 사이클에 후킹(hooking) 되어 보안, 세션 관리, 인증, 메시지 처리 등 다양한 전처리/후처리 기능을 제공합니다. 기본 설정에는 보안 관련 SecurityMiddleware, 세션을 위한 SessionMiddleware, 공통 동작을 위한 CommonMiddleware, CSRF 방지를 위한 CsrfViewMiddleware, 인증을 위한 AuthenticationMiddleware, 메시지 기능의 MessageMiddleware, 클릭재킹 방지용 XFrameOptionsMiddleware 등이 등록되어 있습니다.

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

미들웨어의 순서가 중요합니다. 예를 들어, CsrfViewMiddleware는 CSRF 토큰 검사를 위해 SessionMiddleware보다 뒤에 위치해야 합니다. 필요한 경우 CORS 헤더 처리를 위한 CorsMiddleware 등 추가 미들웨어를 설치하고 이 리스트에 포함시킬 수도 있습니다. (단, 추가하는 미들웨어의 권장 위치를 패키지 문서에서 확인해야 합니다.)

DATABASES (데이터베이스 설정)

DATABASES 설정은 프로젝트에서 사용할 데이터베이스들의 연결 정보를 담고 있습니다. 기본적으로 Django는 SQLite 데이터베이스를 사용하도록 설정되어 있으며, 이는 파일 기반 DB라 설정이 간편하고 개발 및 소규모 프로젝트에 적합합니다. 설정 형식은 파이썬 딕셔너리로, 키는 데이터베이스 **별칭(alias)**이고 값은 해당 DB의 설정 딕셔너리입니다. 최소한 default 키에 대한 설정이 필요하며, 여러 데이터베이스를 병행해서 사용할 수도 있습니다.

  • 기본 SQLite 설정 예시 (프로젝트 시작 시 기본값):위 설정으로 로컬 파일 데이터베이스(db.sqlite3)를 사용합니다. SQLite는 별도 서버가 필요 없고 파일로 저장되므로 개발에 편리합니다.
  • DATABASES = { "default": { "ENGINE": "django.db.backends.sqlite3", "NAME": BASE_DIR / "db.sqlite3", } }
  • 다른 DB 엔진 사용: 운영 환경에서는 성능과 기능을 위해 PostgreSQL, MySQL 등 데이터베이스 서버를 사용하는 경우가 많습니다. 장고에서 지원하는 주요 DB 엔진으로는 'django.db.backends.postgresql', 'django.db.backends.mysql', 'django.db.backends.sqlite3', 'django.db.backends.oracle' 등이 있으며, 설정에서 ENGINE 값을 해당 문자열로 교체하고 NAME, USER, PASSWORD, HOST, PORT 등의 접속 정보를 추가 지정하면 됩니다. 예를 들어 MySQL을 사용할 경우 설정을 다음과 같이 변경할 수 있습니다:데이터베이스 접속 정보를 코드에 하드코딩하는 것은 바람직하지 않으므로, 운영 환경에서는 이 정보를 환경 변수로 불러오거나 별도 파일에서 관리하는 방법을 사용합니다 (글의 후반부에서 다룹니다).
  • DATABASES = { "default": { "ENGINE": "django.db.backends.mysql", "NAME": "mydatabase", "USER": "dbuser", "PASSWORD": "secret_password", "HOST": "localhost", "PORT": "3306", } }

STATIC_URL (정적 파일 설정)

STATIC_URL은 정적 파일(static files)의 URL 경로를 지정하는 설정입니다. 장고의 정적 파일이란 CSS, JavaScript, 이미지와 같이 코드가 아닌 파일 자원들을 말합니다. 기본값은 "static/"로 설정되며, 예를 들어 STATIC_URL = "static/"이면 정적 파일을 참조할 때 URL이 http://<사이트주소>/static/<파일명> 형태로 구성됩니다.

STATIC_URL = "static/"
STATICFILES_DIRS = [BASE_DIR / "assets"]       # 정적 파일 추가 검색 경로 (개발용, 옵션)
STATIC_ROOT = BASE_DIR / "staticfiles"         # 정적 파일 모음 경로 (배포용)
  • STATICFILES_DIRS: 장고가 기본적으로 각 앱 폴더 내의 static/ 디렉터리와 프로젝트의 static 폴더를 찾지만, 추가적인 정적 파일 경로가 있다면 이 리스트에 경로들을 지정할 수 있습니다. 예를 들어 위처럼 프로젝트 내 assets 폴더를 지정하면, 거기에 있는 정적 파일들도 함께 관리됩니다.
  • STATIC_ROOT: 배포(프로덕션) 환경에서 사용되는 경로입니다. python manage.py collectstatic 명령을 실행하면 모든 정적 파일을 이 경로로 복사하게 되며, 실제 웹 서버(Nginx, Apache 등)가 이 디렉토리의 파일들을 서비스하도록 설정합니다. 개발 단계에서는 장고 개발 서버(runserver)가 정적 파일을 자동 제공하지만, 운영 환경에서는 DEBUG=False 상태에서 반드시 collectstatic으로 정적 파일을 모으고 웹서버가 제공하도록 설정해야 합니다.

💡 참고: 미디어 파일(MEDIA_URL/MEDIA_ROOT) 설정도 settings.py에서 다룹니다. 미디어 파일은 사용자가 업로드하는 파일들을 가리키며, 정적 파일과 구분됩니다. 필요할 경우 MEDIA_URL과 MEDIA_ROOT를 설정하고, 개발 시에는 DEBUG 모드에서만 미디어 파일을 서빙하도록 URL 패턴을 추가합니다.

개발/배포 환경별 설정 분리하기

하나의 settings.py 파일로 모든 환경(dev, prod)을 관리할 수도 있지만, 개발(environment)별로 설정을 분리하면 보다 안전하고 편리하게 운영할 수 있습니다. 예를 들어, 개발 환경에서는 디버그를 활성화하고 간편한 설정을 쓰는 반면, 운영 환경에서는 디버그를 끄고 보안 설정을 강화하는 등 차이가 있습니다. 이러한 설정 분리는 보안과 유지보수 측면에서 큰 이점이 있습니다.

일반적으로 설정 분리는 아래와 같은 폴더 구조로 구현합니다:

myproject/
└── myproject/
    ├── settings/
    │   ├── __init__.py        <- 환경에 따라 자동으로 설정을 불러오는 역할
    │   ├── base.py            <- 공통 설정 파일
    │   ├── development.py     <- 개발 환경용 설정
    │   └── production.py      <- 운영 환경용 설정
  • base.py: 모든 환경에서 공통으로 사용하는 기본 설정을 작성합니다. (예: INSTALLED_APPS, MIDDLEWARE, 기본 DATABASES 등)
  • development.py: 개발 환경 전용 설정을 작성합니다. 보통 from .base import *로 기본 설정을 불러온 뒤, DEBUG = True, ALLOWED_HOSTS = [] (또는 로컬호스트), 개발용 데이터베이스 설정 등을 덮어씌웁니다.
  • production.py: 운영 환경 전용 설정을 작성합니다. 역시 base를 불러온 후 DEBUG = False, ALLOWED_HOSTS = ['배포도메인'], 보안 강화 옵션(CSRF_COOKIE_SECURE = True 등)과 운영 DB 설정 등을 지정합니다.

예시를 코드로 보면 다음과 같습니다:

# myproject/settings/base.py
DEBUG = False
ALLOWED_HOSTS = []
INSTALLED_APPS = [ ... ]  # 공통 앱 설정 등
# ... (공통 설정 지속)

# myproject/settings/development.py
from .base import *
DEBUG = True
ALLOWED_HOSTS = []  # 개발 단계에서는 제한 없음 (로컬호스트 허용)

# myproject/settings/production.py
from .base import *
DEBUG = False
ALLOWED_HOSTS = ['mywebsite.com']
CSRF_COOKIE_SECURE = True     # 배포 환경용 추가 설정 예시
SESSION_COOKIE_SECURE = True  # (쿠키를 HTTPS에서만 전달하도록)

이렇게 환경별로 설정 파일을 분리한 후에는, 프로젝트를 실행할 때 어떤 설정을 사용할지 Django에 알려주어야 합니다. 방법은 두 가지입니다:

  • 명령행 옵션 사용: manage.py 실행 시 --settings 옵션으로 경로를 지정합니다. 예를 들어 개발 서버를 띄울 때 python manage.py runserver --settings=myproject.settings.development 처럼 실행하여 개발 설정을 적용할 수 있습니다. 운영 서버에서는 --settings=myproject.settings.production을 지정하여 실행합니다.
  • 환경 변수 사용: 운영 환경에서는 시스템 환경변수 DJANGO_SETTINGS_MODULE을 설정하여 Django가 자동으로 해당 설정을 사용하게 할 수 있습니다. DJANGO_SETTINGS_MODULE 값을 myproject.settings.production으로 지정하면 (export DJANGO_SETTINGS_MODULE=myproject.settings.production 또는 윈도우의 set 명령), manage.py runserver 실행 시 별도 옵션 없이도 그 설정을 로드합니다.

이러한 방법으로 개발 vs. 운영 환경에 맞는 설정을 로드하면, 예를 들어 DEBUG 모드나 데이터베이스, ALLOWED_HOSTS 등이 환경별로 다르게 적용되어 편리합니다. 설정 분리를 제대로 해두지 않으면, 운영 배포 시 DEBUG = False로 전환할 때 ALLOWED_HOSTS를 누락하여 발생하는 오류(DEBUG=False에서 Allowed hosts 미설정 시 400 응답) 등을 겪을 수 있으니 주의해야 합니다.

설정을 깔끔하게 관리하는 팁 (환경 변수, Decouple 등)

마지막으로, settings.py를 더욱 깔끔하고 안전하게 관리하는 방법으로 환경 변수(.env) 활용을 소개합니다. 프로젝트 소스 코드에 직접 민감한 설정값(예: SECRET_KEY, DB 비밀번호)을 적어두면 보안에 취약하고, 코드를 공개 저장소에 올릴 때 문제가 됩니다. 이를 해결하기 위해 환경 변수 또는 별도 설정 파일에 민감정보를 분리하고, settings.py에서는 이를 불러와 사용하는 것이 좋습니다.

대표적인 방법이 python-decouple 패키지나 python-dotenv를 활용하는 것입니다. 여기서는 python-decouple 사용 예시를 들어보겠습니다:

  • python-decouple 설치: 먼저 pip install python-decouple로 패키지를 설치합니다.
  • .env 파일 생성: 프로젝트 루트 디렉터리에 .env 파일을 만들고, 공개하면 안 되는 값들을 키=값 형태로 작성합니다. 예를 들어:.env 파일에 위와 같이 내용을 넣어두면 Git 등에 올리지 않고도 설정 값을 관리할 수 있습니다.
  • SECRET_KEY=prod-secret-key-123!@# DEBUG=False DB_NAME=mydatabase DB_USER=mydbuser DB_PASSWORD=s3cr3tpass
  • settings.py 에서 불러오기: 이제 settings.py 상단에 from decouple import config를 임포트한 뒤, 기존 상수를 config()로 치환합니다. 예를 들면:위 코드에서 config('SECRET_KEY')는 .env 파일에 있는 SECRET_KEY 값을 불러오고, config('DEBUG', cast=bool)은 문자열로 저장된 DEBUG 값을 불리언으로 변환해 가져옵니다. 이렇게 하면 실제 비밀 키나 비밀번호 등이 코드에 직접 드러나지 않고도 설정을 적용할 수 있습니다.
  • from decouple import config SECRET_KEY = config('SECRET_KEY') DEBUG = config('DEBUG', default=False, cast=bool) DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': config('DB_NAME'), 'USER': config('DB_USER'), 'PASSWORD': config('DB_PASSWORD'), # ... 기타 옵션 } }
  • python-dotenv 사용: python-decouple 대신 python-dotenv 패키지를 사용할 수도 있습니다. 원리는 비슷하지만, .env 파일을 자동으로 로드하도록 설정하거나, os.environ으로 값을 가져오는 형태로 동작합니다. 예를 들어 .env 파일 작성 후 python-dotenv를 통해 환경 변수를 읽어 os.environ.get('SECRET_KEY')로 사용하는 방식입니다.

이러한 도구들을 활용하면 개발 환경과 운영 환경에서 각기 다른 .env 파일을 두고 설정을 관리하기도 쉽습니다. 예를 들어 .env.dev, .env.prod 파일을 분리하여, 운영 배포 시에는 운영용 환경 변수만 로드하는 식입니다.

지금까지 Django의 settings.py 주요 항목과 활용법을 살펴보았습니다. 요약하면, settings.py는 Django 프로젝트의 모든 설정을 총괄하는 파일로서, DEBUG 모드나 데이터베이스, 정적 파일, 설치 앱 등 핵심 옵션들을 관리합니다. 입문 단계에서는 필요한 최소한으로만 건드리게 되지만, 점차 프로젝트 규모가 커지면 환경별 설정 분리와 민감정보 관리 등이 중요해집니다. 이번 글의 내용을 바탕으로, 여러분의 Django 프로젝트에서도 settings.py를 잘 활용하여 개발 단계부터 배포 단계까지 안정적이고 효율적인 설정 관리를 해보세요! 🎉

참고 자료: Django 공식 문서 및 여러 블로그의 정리 내용등. 각 설정 항목에 대한 보다 자세한 내용은 Django 공식 문서의 Settings 항목 설명서에서 확인할 수 있습니다.