Настройки проекта в Django: с чего начать новичку

После django-admin startproject вы получаете файл settings.py на 120 строк, и половина из них выглядит как магия. К концу этой статьи вы будете понимать, за что отвечают основные параметры, вынесете секреты из кода в переменные окружения и настроите базу данных на PostgreSQL. Займёт около 30–40 минут, если Python и Django уже установлены.

Материал написан для Django 5.x. В версиях 4.x структура settings.py почти та же, отличия отмечу отдельно.

Что нужно иметь до начала

• Python 3.10 или новее (Django 5.x требует минимум 3.10).
• Установленный Django: проверьте командой python -m django --version — должна вывестись версия вида 5.0.6.
• Созданный проект: django-admin startproject mysite. Внутри появится папка mysite/ с файлом settings.py.
• Установленный пакет python-dotenv, если хотите хранить секреты в файле .env: pip install python-dotenv.
• Для PostgreSQL — установленный сервер БД и драйвер: pip install psycopg[binary].

Все команды ниже запускаются из корня проекта — папки, где лежит manage.py.

Что вообще лежит в settings.py

Это обычный Python-файл. Django импортирует его при старте и читает переменные верхнего уровня. Значит, всё, что вы пишете, — это присваивание Python-переменных, а не какой-то особый синтаксис конфигов.

Ключевые параметры, которые встречает новичок:

Шаг 1. Выньте секреты из кода

По умолчанию SECRET_KEY лежит прямо в settings.py открытым текстом. Если вы зальёте проект на GitHub как есть — ключ уедет в публичный доступ. Вынесем его и DEBUG в переменные окружения.

Создайте в корне проекта файл .env:

# .env — этот файл НЕ коммитим в git
SECRET_KEY=замените-на-свой-длинный-случайный-ключ
DEBUG=True

Сгенерировать новый ключ можно так:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Скопируйте вывод в .env вместо заглушки. Теперь правим начало settings.py:

import os
from pathlib import Path
from dotenv import load_dotenv

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

# Читаем переменные из файла .env в корне проекта
load_dotenv(BASE_DIR / ".env")

SECRET_KEY = os.environ["SECRET_KEY"]

# os.environ возвращает строку, поэтому сравниваем со строкой
DEBUG = os.environ.get("DEBUG", "False") == "True"

Проверка: запустите python manage.py runserver. Если сервер стартовал без ошибки KeyError: 'SECRET_KEY' — переменные читаются.

Сразу добавьте .env в .gitignore, чтобы файл не попал в репозиторий:

# .gitignore
.env
__pycache__/
*.pyc
db.sqlite3

Правило простое: если строку с секретом видно в истории git, считайте секрет скомпрометированным. Ротация ключа задним числом дороже, чем аккуратность на старте.

Шаг 2. Настройте ALLOWED_HOSTS

Пока DEBUG=True, Django разрешает запросы с localhost и 127.0.0.1 автоматически. Но как только вы поставите DEBUG=False, пустой ALLOWED_HOSTS заблокирует все запросы с ошибкой Bad Request (400).

Задайте домены явно:

# Для локальной разработки
ALLOWED_HOSTS = ["127.0.0.1", "localhost"]

# Для боевого сервера добавьте свой домен:
# ALLOWED_HOSTS = ["example.com", "www.example.com"]

Проверка: откройте http://127.0.0.1:8000/ — увидите приветственную страницу Django с ракетой.

Шаг 3. Переключитесь на PostgreSQL

По умолчанию Django использует SQLite — файл db.sqlite3. Для учёбы это нормально, но для реального проекта берут PostgreSQL. Сначала создайте базу и пользователя в самом Postgres, затем пропишите доступ.

Добавьте параметры подключения в .env:

DB_NAME=mysite
DB_USER=mysite_user
DB_PASSWORD=YOUR_DB_PASSWORD
DB_HOST=localhost
DB_PORT=5432

И перепишите блок DATABASES в settings.py:

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],
        "HOST": os.environ["DB_HOST"],
        "PORT": os.environ["DB_PORT"],
    }
}

Проверка: запустите python manage.py migrate. Django применит встроенные миграции. Если в конце появились строки Applying ... OK — подключение работает.

Шаг 4. Язык и часовой пояс

По умолчанию проект на английском и в UTC. Для российского проекта чаще ставят:

LANGUAGE_CODE = "ru-ru"
TIME_ZONE = "Europe/Moscow"
USE_I18N = True
USE_TZ = True

USE_TZ = True означает, что Django хранит время в базе в UTC, а на отображение переводит в ваш TIME_ZONE. Это правильное поведение — оставьте его включённым.

Шаг 5. Создайте своё приложение и подключите его

Django-проект состоит из приложений. Создайте первое:

python manage.py startapp blog

Затем добавьте его в INSTALLED_APPS. Строка с AppConfig предпочтительнее короткого имени — так Django точно найдёт конфигурацию приложения:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # ваше приложение
    "blog.apps.BlogConfig",
]

Проверка: перезапустите сервер. Ошибок про blog быть не должно. Модели из этого приложения теперь попадут в миграции.

Если не получилось

• KeyError: 'SECRET_KEY' — файл .env не найден или лежит не в корне. Проверьте путь в load_dotenv() и что переменная в .env написана без пробелов вокруг =.
• django.db.utils.OperationalError: connection refused — сервер PostgreSQL не запущен или DB_HOST/DB_PORT указаны неверно.
• password authentication failed for user — не совпадают пароль или имя пользователя из .env с тем, что задано в самой БД.
• ModuleNotFoundError: No module named 'psycopg' — не установлен драйвер. Выполните pip install psycopg[binary].
• Bad Request (400) после DEBUG=False — домен запроса не входит в ALLOWED_HOSTS. Добавьте его в список.

Что делать дальше

Когда базовый settings.py в порядке, следующий шаг — разделить настройки на окружения. Держать один файл для разработки и прода неудобно: значения DEBUG, ALLOWED_HOSTS и базы данных отличаются. Распространённый приём — папка settings/ с файлами base.py, dev.py, prod.py и выбор нужного через переменную DJANGO_SETTINGS_MODULE. Разбор такой структуры — отдельная тема, здесь мы собрали рабочий минимум для одного окружения.

Дальше стоит настроить статику (STATIC_URL, STATIC_ROOT) перед деплоем и прочитать про команду python manage.py check --deploy — она подсказывает, какие настройки небезопасны для прода.