Клонирование и запуск Django‑проекта локально

Что потребуется

• Python 3.8+ (рекомендуется 3.10)
• Базовые знания Django (модели, миграции, settings.py)
• pip или pipenv
• Инструмент для виртуальных окружений (pipenv или venv)
• Git и аккаунт GitHub
• Базовые навыки работы с терминалом
• PostgreSQL (для примера в этой инструкции)

Важно: термин «виртуальное окружение» — изолированная среда Python для проекта.

1. Клонирование проекта с GitHub

Откройте страницу репозитория на GitHub. Нажмите зелёную кнопку Code и скопируйте HTTP‑ или SSH‑ссылку. Если вы планируете вносить изменения и отправлять пул‑реквесты, сначала сделайте fork репозитория в свой аккаунт, затем клонируйте уже ваш fork.

Создайте папку для проекта и перейдите в неё:

mkdir clone_boma
cd clone_boma

Клонируйте репозиторий:

git clone 

Пример (HTTP):

git clone https://github.com/Dindihub/Boma-watch.git

После клонирования проверьте содержимое каталога командой ls или через файловый менеджер.

2. Осмотрите файлы проекта

Ищите ключевые артефакты: manage.py, папку проекта (с settings.py), Pipfile/Pipfile.lock или requirements.txt, файл .env.example или README. README обычно содержит специфичные для проекта инструкции по запуску.

Если встречается Pipfile — проект использует Pipenv; если requirements.txt — стандартный pip.

3. Настройка виртуального окружения

Лучше всегда запускать проект в отдельном виртуальном окружении, чтобы зависимости не конфликтовали с системными пакетами.

Если проект использует Pipenv (Pipfile + Pipfile.lock):

1. Иногда старые Pipfile приводят к ошибкам вроде:

ModuleNotFoundError: No module named 'distutils.core'

2. Удалите старое окружение и временные Pipfile, затем установите заново под вашей версией Python:

pipenv --rm
rm Pipfile*
pipenv install --python 3.10

3. Установите дополнительные пакеты, если нужно:

pipenv install requests

4. Активируйте оболочку окружения:

pipenv shell

Если вы предпочитаете venv + pip:

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate     # Windows (PowerShell или CMD)
pip install -r requirements.txt

Чтобы зафиксировать текущие зависимости в файл requirements.txt:

pip freeze > requirements.txt

Советы по устранению конфликтов:

• Если pipenv/pip устанавливает пакеты с ошибками компиляции, установите системные зависимости (например, build‑tools, libpq-dev для psycopg2 на Linux).
• Для macOS используйте Homebrew, для Ubuntu — apt, для Windows — установщики бинарных колёс (.whl), если сборка не проходит.

4. Установка и подключение базы данных

В данном проекте используется PostgreSQL. Вы можете выбрать другую СУБД, но при смене нужны правки в settings.py и установленные драйверы.

Установите PostgreSQL по инструкции для вашей ОС. Затем выполните в терминале:

sudo -i -u postgres
psql
postgres=# create database new_boma;
postgres=# \l

Команда \l в psql показывает список баз данных.

В settings.py укажите параметры подключения (замените на свои):

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'new_boma',
        'USER': 'postgres',
        'PASSWORD': 'password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

Проверьте и скорректируйте TIME_ZONE в settings.py под ваш часовой пояс, чтобы корректно отображались временные метки.

Установка драйвера psycopg2 (поддерживает работу с изображениями, BLOB и т.д.):

pipenv install psycopg2
# или для venv
pip install psycopg2-binary

Если установка psycopg2 падает из‑за отсутствия заголовков libpq, установите системные зависимости (на Ubuntu: apt install libpq-dev python3-dev).

5. Секретный ключ и переменные окружения

Секретный ключ Django (SECRET_KEY) не должен храниться в репозитории публично. Обычно ключ хранят в .env файле или используют переменные окружения.

Пример безопасного подхода: создайте файл .env (добавьте .env в .gitignore) и поместите туда ключы и пароли.

Как быстро сгенерировать секретный ключ в Python:

from django.core.management.utils import get_random_secret_key
print(get_random_secret_key())

Затем в settings.py можно загрузить ключ из переменной окружения (пример с python‑decouple или os.environ):

import os
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'fallback-key-for-dev')

Запишите в .env:

DJANGO_SECRET_KEY='ваш-секретный-ключ'
DATABASE_PASSWORD='ваш-пароль'

И используйте django‑environ, python‑decouple или os.environ для чтения.

6. Миграции базы данных

Создайте миграции и примените их:

python manage.py makemigrations
python manage.py migrate

Типичные ошибки и их исправление:

• MissingModuleError: установите отсутствующие зависимости через pipenv/pip.
• OperationalError при подключении к Postgres: проверьте правильность параметров HOST/PORT/USER/PASSWORD и что сервер запущен.
• Разрыв схемы миграций (конфликт версий миграций): при необходимости используйте

python manage.py showmigrations
python manage.py migrate --fake  

Никогда не применяйте –fake без понимания последствий — это может десинхронизировать состояние БД с миграциями.

Если миграции не применяются из‑за отсутствия app в INSTALLED_APPS, добавьте приложение в settings.py.

7. Запуск проекта локально

Запустите dev‑сервер:

python manage.py runserver

Откройте http://127.0.0.1:8000/ в браузере и проверьте, отображается ли главный экран.

Если сайт не открывается:

• Проверьте логи терминала на наличие ошибок.
• Убедитесь, что в DEBUG=True (только для локальной разработки).
• Проверьте, что порт 8000 не занят другим процессом.

Частые проблемы и быстрые решения

• Неполадки с зависимостями: пересоздайте виртуальное окружение и установите зависимости заново.
• Проблемы с компиляцией пакетов: установите системные dev‑пакеты (build‑essentials, libpq‑dev и т.д.).
• Ошибки миграций: проверьте состояние миграций и при необходимости применяйте –fake только осознанно.
• Неправильный SECRET_KEY или отсутствие .env: проверьте наличие переменных окружения.

Чеклист перед созданием PR

• Проект собирается и запускается локально без ошибок
• Все миграции применены и протестированы
• Нет хардкодированных паролей или ключей в репозитории
• Внесённые изменения покрыты тестами (если есть тестовая база)
• Обновлён requirements.txt/Pipfile при изменении зависимостей

Критерии приёмки

• Приложение запускается и основные страницы открываются
• Миграции применены без ошибок
• Данные тестовых сценариев сохраняются и читаются из БД
• Отсутствуют конфликты зависимостей и системных ошибок при установке

Плейбук при возникновении критической ошибки при запуске

1. Остановите сервер (Ctrl+C).
2. Активируйте виртуальное окружение и запустите:

pip freeze

3. Сравните списки зависимостей с requirements.txt/Pipfile.lock.
4. Удалите окружение и установите заново (pipenv –rm или recreate venv).
5. Проверьте логи Postgres и доступ по учётным данным.
6. Если миграции не применяются — экспортируйте дамп БД и восстановите в чистом состоянии.

Диаграмма принятия решения при конфликте зависимостей

flowchart TD
  A[Начало: ошибки при установке зависимостей] --> B{Ошибка сборки нативного расширения?}
  B -- Да --> C[Установить системные dev‑пакеты]
  B -- Нет --> D{Проблема совместимости версии Python?}
  D -- Да --> E[Создать окружение с требуемой версией Python]
  D -- Нет --> F{Неправильная версия пакета в Pipfile/requirements?}
  F -- Да --> G[Синхронизировать версии, запустить pipenv lock / pip install]
  F -- Нет --> H[Проверить логи и искать специфичную ошибку]
  C --> G
  E --> G
  G --> I[Пересоздать окружение и повторить установку]
  H --> I
  I --> J[Проверить работоспособность проекта]

Рекомендации по совместимости и миграции

• Указывайте точные версии критичных библиотек в Pipfile.lock или requirements.txt, чтобы другие разработчики воспроизводили окружение.
• Для долгоживущих проектов используйте контейнеризацию (Docker) — это уменьшает «работает у меня» проблемы.
• Документируйте команды установки СУБД и зависимости в README.

Локальные нюансы и советы для Windows

• Пути и команды активации venv отличаются: используйте .venv\Scripts\activate.
• Для сборки psycopg2 на Windows проще ставить psycopg2‑binary или использовать готовые wheel‑файлы.
• Проверяйте установку MSVC Build Tools при ошибках компиляции расширений.

Итог и ключевые идеи

Клонирование Django‑проекта — это не только git clone. Ключевые шаги: создать чистое виртуальное окружение, правильно установить зависимости, подключить базу данных и безопасно задать секретные ключи. Если следовать этому руководству, вы сведёте к минимуму ошибки при запуске и сможете быстрее приступить к разработке новых фич.

Важно: для публикации изменений не оставляйте секреты в репозитории и всегда тестируйте миграции на копии базы.