mod: Все для контейнера в dev-режиме.
This commit is contained in:
407
SETUP.md
407
SETUP.md
@@ -1,330 +1,187 @@
|
||||
# 🚀 SETUP.md — Первичная настройка Окнардии
|
||||
|
||||
**Версия**: 0.2.0 | **Дата**: 16.04.2026
|
||||
**Версия**: 0.2.0 | **Дата**: 18.05.2026 | **Docker**: ✅ Поддерживается
|
||||
|
||||
Этот документ описывает пошаговую настройку проекта для разработки и деплоя.
|
||||
|
||||
## 📋 Предварительные требования
|
||||
---
|
||||
|
||||
- **Python**: 3.12+
|
||||
- **Django**: 6.0+
|
||||
- **MariaDB/MySQL**: 5.7+ или 8.0+
|
||||
- **Redis** (опционально, для кеширования): 6.0+
|
||||
- **Poetry** (для управления зависимостями)
|
||||
## 🐳 Быстрый старт: Docker Dev Environment
|
||||
|
||||
### На macOS:
|
||||
### 1️⃣ Запуск контейнера
|
||||
|
||||
```bash
|
||||
# Установка зависимостей (если не установлены)
|
||||
brew install mariadb-connector-c
|
||||
brew install redis # опционально
|
||||
cd /Users/e-serg/PRJ/2022-oknardia
|
||||
docker compose -f docker-compose.local.yml up --build
|
||||
```
|
||||
|
||||
## 🔑 Шаг 1: Конфигурация секретов
|
||||
Сайт будет доступен на **http://localhost:8060**
|
||||
|
||||
### 1.1 Создайте файл `my_secret.py`
|
||||
### 2️⃣ Основные команды
|
||||
|
||||
```bash
|
||||
cd oknardia/oknardia
|
||||
cp my_secret.py.template my_secret.py
|
||||
nano my_secret.py # отредактируйте значения
|
||||
# Просмотр логов в реальном времени
|
||||
docker compose -f docker-compose.local.yml logs web -f
|
||||
|
||||
# Зайти в контейнер (bash)
|
||||
docker compose -f docker-compose.local.yml exec web bash
|
||||
|
||||
# Перезагрузить контейнер
|
||||
docker compose -f docker-compose.local.yml restart web
|
||||
|
||||
# Остановить контейнер
|
||||
docker compose -f docker-compose.local.yml down
|
||||
```
|
||||
|
||||
**Что нужно заполнить:**
|
||||
- IP адреса и хосты (MY_HOST_HOME2, MY_DATABASE_HOST_DEV2)
|
||||
- Пароль БД (MY_DATABASE_PASSWORD_DEV)
|
||||
- Email credentials (MY_EMAIL_HOST_USER_DEV, MY_EMAIL_HOST_PASSWORD_DEV)
|
||||
- Пути к файлам (MY_MEDIA_ROOT_DEV2, MY_STATIC_ROOT_DEV2)
|
||||
- SECRET_KEY (сгенерируйте новый!)
|
||||
**✨ Особенности:**
|
||||
- ✅ **Live reload** — при изменении кода автоматически перезагружается
|
||||
- ✅ **Синхронизция файлов** — база, медиа, статика синхронизированы с хостом
|
||||
- ✅ **Миграции автоматические** — применяются при каждом старте
|
||||
- ✅ **DEBUG режим** — подробные ошибки и админка
|
||||
|
||||
### 1.2 (Опционально) Создайте файл `.env.local`
|
||||
👁️ **Подробнее про Docker разработку** → см. раздел **"🐳 Docker Development"** ниже.
|
||||
|
||||
```bash
|
||||
cd /path/to/project
|
||||
cp .env.example .env.local
|
||||
nano .env.local # отредактируйте значения
|
||||
---
|
||||
|
||||
## 🐳 Docker Development
|
||||
|
||||
### Структура контейнера
|
||||
|
||||
```
|
||||
/home/app/ # PROJECT_ROOT
|
||||
├── oknardia/ # основная папка Django
|
||||
│ ├── manage.py # точка входа
|
||||
│ ├── oknardia/ # конфиг Django
|
||||
│ ├── web/ # приложение
|
||||
│ └── templates/ # шаблоны
|
||||
├── database/ # SQLite БД (синхронизирована)
|
||||
├── public/
|
||||
│ ├── static/ # исходная статика
|
||||
│ ├── static_collected/ # собранная статика
|
||||
│ └── media/ # загруженные файлы
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Примечание**: либо используйте `my_secret.py`, либо `.env.local`, выбирайте удобный способ.
|
||||
### Volume mounts (синхронизация)
|
||||
|
||||
## 🗄️ Шаг 2: Настройка БД
|
||||
|
||||
### 2.1 Создайте БД и пользователя
|
||||
|
||||
```bash
|
||||
# Подключитесь к MySQL
|
||||
mysql -u root -p
|
||||
|
||||
# В MySQL консоли:
|
||||
CREATE DATABASE django_oknardia_dev;
|
||||
CREATE USER 'web'@'localhost' IDENTIFIED BY 'your-password';
|
||||
GRANT ALL PRIVILEGES ON django_oknardia_dev.* TO 'web'@'localhost';
|
||||
FLUSH PRIVILEGES;
|
||||
EXIT;
|
||||
```yaml
|
||||
volumes:
|
||||
- .:/home/app
|
||||
```
|
||||
|
||||
### 2.2 Выполните миграции
|
||||
Это монтирует весь проект (`/Users/e-serg/PRJ/2022-oknardia`) в `/home/app` контейнера.
|
||||
|
||||
**Синхронизация:**
|
||||
- Изменения на хосте сразу видны в контейнере
|
||||
- Разные между хостом и контейнером сохраняются на диск
|
||||
- БД и медиа-файлы персистент (не теряются при рестарте контейнера)
|
||||
|
||||
### Миграции в Docker
|
||||
|
||||
```bash
|
||||
cd /path/to/project/oknardia
|
||||
# Автоматические при запуске (через docker-compose command):
|
||||
python manage.py migrate --noinput
|
||||
|
||||
# Или вручную внутри контейнера:
|
||||
docker compose -f docker-compose.local.yml exec web bash
|
||||
python manage.py makemigrations
|
||||
python manage.py migrate
|
||||
|
||||
# Или непосредственно внутри контейнера:
|
||||
docker compose -f docker-compose.local.yml exec web python manage.py migrate
|
||||
```
|
||||
|
||||
### 2.3 Создайте суперпользователя
|
||||
### Установка новых пакетов
|
||||
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
# 1. На хосте добавьте в pyproject.toml:
|
||||
poetry add some_package
|
||||
|
||||
# 2. Пересоберите контейнер:
|
||||
docker compose -f docker-compose.local.yml up --build
|
||||
|
||||
# 3. Зависимости переустановят при старте контейнера
|
||||
```
|
||||
|
||||
## 📦 Шаг 3: Установка зависимостей
|
||||
|
||||
### Вариант 1: Poetry (рекомендуется)
|
||||
### Создание суперюзера (админ)
|
||||
|
||||
```bash
|
||||
# Установите poetry (если не установлен)
|
||||
curl -sSL https://install.python-poetry.org | python3 -
|
||||
|
||||
# Установите зависимости
|
||||
poetry install
|
||||
|
||||
# Активируйте виртуальное окружение
|
||||
poetry shell
|
||||
docker compose -f docker-compose.local.yml exec web python manage.py createsuperuser
|
||||
```
|
||||
|
||||
### Вариант 2: pip (классический способ)
|
||||
### Очистка кеша и статики
|
||||
|
||||
```bash
|
||||
python -m venv venv
|
||||
source venv/bin/activate # На Windows: venv\Scripts\activate
|
||||
pip install -r requirements.txt
|
||||
# Пересоберите статику:
|
||||
docker compose -f docker-compose.local.yml exec web python manage.py collectstatic --clear --noinput
|
||||
|
||||
# Или удалите и пересоздайте:
|
||||
rm -rf ./public/static_collected/*
|
||||
docker compose -f docker-compose.local.yml restart web
|
||||
```
|
||||
|
||||
## 🏃 Шаг 4: Запуск разработки
|
||||
|
||||
### 4.1 Запустите локальный сервер
|
||||
### DEBUG и логирование
|
||||
|
||||
```bash
|
||||
cd oknardia
|
||||
python manage.py runserver
|
||||
# DEBUG=True включен по умолчанию
|
||||
# Смотрите подробные логи:
|
||||
docker compose -f docker-compose.local.yml logs web -f --tail=50
|
||||
|
||||
# Или с фильтром (только ошибки):
|
||||
docker compose -f docker-compose.local.yml logs web --tail=100 | grep -i error
|
||||
```
|
||||
|
||||
Откройте браузер: **http://127.0.0.1:8000**
|
||||
### Типичные проблемы Docker
|
||||
|
||||
### 4.2 Запустите задачи Celery (опционально)
|
||||
**"unable to open database file"**
|
||||
```bash
|
||||
# Проверьте что БД существует:
|
||||
ls -la ./database/oknardia.sqlite3
|
||||
|
||||
# Если нет:
|
||||
cp ./database/oknadria_backup-2026-05-12.sqlite3 ./database/oknardia.sqlite3
|
||||
docker compose -f docker-compose.local.yml restart web
|
||||
```
|
||||
|
||||
**"404 Not Found" для статики**
|
||||
```bash
|
||||
# Пересоберите статику:
|
||||
docker compose -f docker-compose.local.yml exec web python manage.py collectstatic --noinput
|
||||
docker compose -f docker-compose.local.yml restart web
|
||||
```
|
||||
|
||||
**Контейнер падает**
|
||||
```bash
|
||||
# Смотрите полные логи:
|
||||
docker compose -f docker-compose.local.yml logs web --tail=200
|
||||
|
||||
# Часто ошибка в settings.py или import'ах
|
||||
```
|
||||
|
||||
**"Connection refused" при обращении в БД**
|
||||
```bash
|
||||
# Проверьте что контейнер запущен:
|
||||
docker compose -f docker-compose.local.yml ps
|
||||
|
||||
# Перезагрузитесь:
|
||||
docker compose -f docker-compose.local.yml down && docker compose -f docker-compose.local.yml up
|
||||
```
|
||||
|
||||
### Очистка Docker
|
||||
|
||||
```bash
|
||||
celery -A oknardia worker -l info
|
||||
# Удалить контейнер и образ:
|
||||
docker compose -f docker-compose.local.yml down -v
|
||||
|
||||
# Удалить весь Docker мусор:
|
||||
docker system prune -a --volumes
|
||||
```
|
||||
|
||||
## 📁 Шаг 5: Создание необходимых директорий
|
||||
|
||||
```bash
|
||||
# Статика и медиа файлы
|
||||
mkdir -p public/media
|
||||
mkdir -p public/static
|
||||
mkdir -p public/static/img/_flap.cfg
|
||||
mkdir -p public/static/img/_miniflap.cfg
|
||||
|
||||
# Логи
|
||||
mkdir -p logs
|
||||
|
||||
# Сгенерируйте статику
|
||||
python manage.py collectstatic --noinput
|
||||
```
|
||||
|
||||
## 🧪 Шаг 6: Тестирование
|
||||
|
||||
```bash
|
||||
# Запустите тесты
|
||||
python manage.py test
|
||||
|
||||
# С покрытием (если установлен coverage)
|
||||
coverage run --source='.' manage.py test
|
||||
coverage report
|
||||
```
|
||||
|
||||
## 🔐 Шаг 7: Проверка безопасности
|
||||
|
||||
### 7.1 Django встроенная проверка
|
||||
|
||||
```bash
|
||||
python manage.py check --deploy
|
||||
```
|
||||
|
||||
### 7.2 Проверка на утечки секретов
|
||||
|
||||
```bash
|
||||
# Установите инструмент
|
||||
pip install truffleHog
|
||||
|
||||
# Проверьте репозиторий
|
||||
truffleHog filesystem . --json
|
||||
```
|
||||
|
||||
## ✅ Проверка готовности
|
||||
|
||||
Убедитесь, что все работает:
|
||||
|
||||
```bash
|
||||
# 1. Статус БД
|
||||
python manage.py dbshell < /dev/null && echo "✓ Database OK"
|
||||
|
||||
# 2. Статус приложений Django
|
||||
python manage.py check && echo "✓ Django OK"
|
||||
|
||||
# 3. Статус файлов
|
||||
test -d public/media && test -d public/static && echo "✓ Directories OK"
|
||||
|
||||
# 4. Тесты
|
||||
python manage.py test 2>&1 | tail -5
|
||||
```
|
||||
|
||||
## 🚀 Развертывание на продакшене
|
||||
|
||||
### Для разных хостов
|
||||
|
||||
**Masterhost VDS:**
|
||||
```bash
|
||||
# Установка окружения
|
||||
export DJANGO_SECRET_KEY="your-production-key"
|
||||
export DATABASE_PASSWORD="production-db-password"
|
||||
export DATABASE_HOST="localhost"
|
||||
export DEBUG="False"
|
||||
|
||||
# Запуск через uWSGI + Nginx
|
||||
uwsgi --ini config/oknardia.ini
|
||||
```
|
||||
|
||||
**Docker (рекомендуется):**
|
||||
```bash
|
||||
docker build -t oknardia:latest .
|
||||
docker run -d \
|
||||
-e DJANGO_SECRET_KEY="..." \
|
||||
-e DATABASE_PASSWORD="..." \
|
||||
-p 8000:8000 \
|
||||
oknardia:latest
|
||||
```
|
||||
|
||||
## 🛠️ Полезные команды
|
||||
|
||||
```bash
|
||||
# Управление миграциями
|
||||
python manage.py makemigrations # Создать миграцию
|
||||
python manage.py migrate # Применить миграции
|
||||
python manage.py migrate --fake-initial # Подделать первую миграцию
|
||||
|
||||
# Управление данными
|
||||
python manage.py shell # Интерпретатор Python с контекстом Django
|
||||
python manage.py dumpdata > backup.json # Резервная копия данных
|
||||
python manage.py loaddata backup.json # Восстановление данных
|
||||
|
||||
# Статика и медиа
|
||||
python manage.py collectstatic # Собрать статику для продакшена
|
||||
python manage.py findstatic # Найти файлы статики
|
||||
|
||||
# Администрирование
|
||||
python manage.py createsuperuser # Создать администратора
|
||||
python manage.py changepassword username # Изменить пароль
|
||||
|
||||
# Очистка
|
||||
python manage.py clearsessions # Удалить старые сессии
|
||||
python manage.py remove_stale_contenttypes # Удалить устаревшие типы контента
|
||||
|
||||
# Служебные
|
||||
python manage.py check # Проверить конфигурацию
|
||||
python manage.py check --deploy # Проверка для продакшена
|
||||
python manage.py generate_sitemaps # Оффлайн генерация sitemap XML
|
||||
python manage.py regenerate_seria_prerender --dry-run # Проверка пересборки pre-render шаблонов серий
|
||||
python manage.py regenerate_seria_prerender --force # Принудительная пересборка pre-render шаблонов серий
|
||||
```
|
||||
|
||||
### Пересборка pre-render шаблонов серий (рекомендуемый сценарий)
|
||||
|
||||
Шаблоны для `catalog_seria_info` пересобираются оффлайн management-командой, без reload из кода Django.
|
||||
|
||||
```bash
|
||||
cd /path/to/project
|
||||
poetry run python oknardia/manage.py regenerate_seria_prerender --force
|
||||
# затем (опционально) один внешний reload процесса приложения, если это требуется вашей конфигурацией
|
||||
# sudo systemctl reload gunicorn
|
||||
```
|
||||
|
||||
Для выборочной пересборки используйте `--seria-id` несколько раз:
|
||||
|
||||
```bash
|
||||
poetry run python oknardia/manage.py regenerate_seria_prerender --seria-id 843 --seria-id 2100 --force
|
||||
```
|
||||
|
||||
## 📚 Дополнительные ресурсы
|
||||
---
|
||||
## Дополнительные ресурсы
|
||||
|
||||
- [Django документация](https://docs.djangoproject.com/en/stable/)
|
||||
- [AGENTS.md](./AGENTS.md) — архитектура и конвенции проекта
|
||||
- [README.md](./README.md) — основная информация о проекте
|
||||
|
||||
## ❓ Решение проблем
|
||||
|
||||
### Проблема: `mysqlclient` не устанавливается на macOS
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
brew install mariadb-connector-c
|
||||
pip install mysqlclient
|
||||
# или
|
||||
brew unlink mariadb-connector-c # после установки
|
||||
```
|
||||
|
||||
### Проблема: `ModuleNotFoundError: No module named 'oknardia'`
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Убедитесь, что находитесь в правильной директории
|
||||
cd /path/to/project/oknardia
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
### Проблема: `OperationalError: (2002, "Can't connect to local MySQL server")`
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверьте, что MySQL запущен
|
||||
# macOS:
|
||||
brew services start mariadb
|
||||
|
||||
# Linux:
|
||||
sudo systemctl start mysql
|
||||
|
||||
# Проверьте credentials в my_secret.py или .env
|
||||
```
|
||||
|
||||
### Проблема: миграции не применяются
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Проверьте статус миграций
|
||||
python manage.py showmigrations
|
||||
|
||||
# Примените все миграции
|
||||
python manage.py migrate --run-syncdb
|
||||
|
||||
# Если проблема в конкретной миграции
|
||||
python manage.py migrate app_name 0001 --fake
|
||||
python manage.py migrate app_name
|
||||
```
|
||||
|
||||
## 🤝 Общие вопросы
|
||||
|
||||
**Q: Где хранятся секреты?**
|
||||
A: В `my_secret.py` (в .gitignore) или переменных окружения (.env)
|
||||
|
||||
**Q: Как запустить проект без интернета?**
|
||||
A: Установите все зависимости заранее, используйте локальное хранилище медиа
|
||||
|
||||
**Q: Как работает система рейтинга?**
|
||||
A: Смотрите [AGENTS.md](./AGENTS.md), раздел "Система рейтинга и ранжирования"
|
||||
|
||||
---
|
||||
|
||||
**Версия документа**: 1.0
|
||||
**Последнее обновление**: 16.04.2026
|
||||
**Автор**: GitHub Copilot
|
||||
|
||||
|
||||
Reference in New Issue
Block a user