Шаг 01. Проект и настройка

🎯 Цель этапа

На этом шаге мы закладываем фундамент Django-проекта: правильную структуру, виртуальное окружение и настройки через django-environ. Вместо хранения секретных ключей и DSN прямо в settings.py — читаем их из .env по принципу 12-factor app.

После этого шага у нас будет

• Виртуальное окружение и requirements.txt с закреплёнными версиями
• Django-проект с пакетом настроек config/
• settings.py, читающий секреты из .env
• Файл .env с SECRET_KEY, DEBUG, ALLOWED_HOSTS
• python manage.py check — OK

📄 Затрагиваемые файлы

🔨 Шаги

1. Создаём директорию и виртуальное окружение

# Создаём папку проекта
mkdir library_catalog
cd library_catalog

# Создаём виртуальное окружение
python -m venv venv

# Активируем (Windows PowerShell)
venv\Scripts\Activate.ps1

# Проверяем: в начале строки должно появиться (venv)
python --version

2. Устанавливаем зависимости

pip install django==5.0.6 django-environ==0.11.2

# requirements.txt
django==5.0.6
django-environ==0.11.2

3. Создаём Django-проект

# Точка в конце: файлы размещаются прямо в текущей папке
django-admin startproject config .

Итоговая структура после создания:

library_catalog/
├── venv/                   # виртуальное окружение
├── config/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py         # ← будем редактировать
│   ├── urls.py
│   └── wsgi.py
├── manage.py
├── requirements.txt
└── .gitignore              # создадим далее

4. Создаём .env и .gitignore

# .env — НЕ коммитить в git!
SECRET_KEY=django-insecure-replace-this-in-production-use-long-random-string
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost

# .env.example — шаблон, коммитить можно
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost
# DATABASE_URL=postgres://user:pass@localhost/library_catalog

# .gitignore
venv/
__pycache__/
*.pyc
*.pyo
.env
*.sqlite3
db.sqlite3
.mypy_cache/
.pytest_cache/

5. Настраиваем settings.py

# config/settings.py
import environ
from pathlib import Path

# Корень проекта — папка, где лежит manage.py
BASE_DIR = Path(__file__).resolve().parent.parent

# Инициализируем environ и читаем .env
env = environ.Env(
    DEBUG=(bool, False),          # тип и значение по умолчанию
    ALLOWED_HOSTS=(list, []),
)
environ.Env.read_env(BASE_DIR / ".env")

# --- Безопасность ---
SECRET_KEY = env("SECRET_KEY")
DEBUG = env("DEBUG")
ALLOWED_HOSTS = env("ALLOWED_HOSTS")

# --- Приложения ---
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # наши приложения — добавим на шаге 03
]

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",
]

ROOT_URLCONF = "config.urls"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

WSGI_APPLICATION = "config.wsgi.application"

# --- База данных ---
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

# --- Валидация паролей ---
AUTH_PASSWORD_VALIDATORS = [
    {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
    {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
]

# --- Локализация ---
LANGUAGE_CODE = "ru-ru"
TIME_ZONE = "Europe/Moscow"
USE_I18N = True
USE_TZ = True

# --- Статика ---
STATIC_URL = "static/"

# --- Первичный ключ по умолчанию ---
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

🧠 Объяснение логики

Почему config, а не имя проекта?

По умолчанию django-admin startproject library_catalog . создаёт папку library_catalog/ — и потом у вас будет library_catalog/library_catalog/, что запутывает. Имя config явно говорит: здесь конфигурация, а не бизнес-логика. Это распространённое соглашение в Django-сообществе (используется в Two Scoops of Django и многих production-проектах).

12-factor app и django-environ

12-factor app — набор принципов для production-приложений. Принцип III: конфигурация хранится в переменных окружения, не в коде. django-environ позволяет делать это удобно: один .env файл для локальной разработки, настоящие переменные окружения — на сервере.

✅ Проверка

1. Проверка конфигурации

python manage.py check

2. Ожидаемый результат

System check identified no issues (0 silenced).

Диагностика: если что-то пошло не так

• Ошибка: ModuleNotFoundError: No module named 'environ' — venv не активирован или pip install django-environ не выполнено
• Ошибка: django.core.exceptions.ImproperlyConfigured: Set the SECRET_KEY environment variable — файл .env не создан или путь к нему неверный
• Ошибка: FileNotFoundError: ... .env — проверьте, что .env лежит в корне проекта рядом с manage.py

➡️ Что дальше

На следующем шаге мы создадим Django-приложение catalog, подключим его к проекту, запустим первые миграции (встроенные таблицы auth, admin и т.д.) и создадим суперпользователя.

• Готово: venv, Django-проект, settings через .env, check — OK
• Далее (шаг 02): python manage.py startapp catalog, migrate, createsuperuser
• После шага 02 мы впервые откроем Django Admin в браузере