add: initial commit — Django 4.1 project (2022 version), docs, security templates

2026-04-16 15:55:21 +03:00
parent e2091b72b1
commit 5bdb97f5e8
4 changed files with 848 additions and 0 deletions
--- a/SETUP.md
+++ b/SETUP.md
@@ -0,0 +1,311 @@
+# 🚀 SETUP.md — Первичная настройка Окнардии
+
+**Версия**: 0.2.0 | **Дата**: 16.04.2026
+
+Этот документ описывает пошаговую настройку проекта для разработки и деплоя.
+
+## 📋 Предварительные требования
+
+- **Python**: 3.12+
+- **Django**: 6.0+
+- **MariaDB/MySQL**: 5.7+ или 8.0+
+- **Redis** (опционально, для кеширования): 6.0+
+- **Poetry** (для управления зависимостями)
+
+### На macOS:
+
+```bash
+# Установка зависимостей (если не установлены)
+brew install mariadb-connector-c
+brew install redis  # опционально
+```
+
+## 🔑 Шаг 1: Конфигурация секретов
+
+### 1.1 Создайте файл `my_secret.py`
+
+```bash
+cd oknardia/oknardia
+cp my_secret.py.template my_secret.py
+nano my_secret.py  # отредактируйте значения
+```
+
+**Что нужно заполнить:**
+- 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 (сгенерируйте новый!)
+
+### 1.2 (Опционально) Создайте файл `.env.local`
+
+```bash
+cd /path/to/project
+cp .env.example .env.local
+nano .env.local  # отредактируйте значения
+```
+
+**Примечание**: либо используйте `my_secret.py`, либо `.env.local`, выбирайте удобный способ.
+
+## 🗄️ Шаг 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;
+```
+
+### 2.2 Выполните миграции
+
+```bash
+cd /path/to/project/oknardia
+python manage.py migrate
+```
+
+### 2.3 Создайте суперпользователя
+
+```bash
+python manage.py createsuperuser
+```
+
+## 📦 Шаг 3: Установка зависимостей
+
+### Вариант 1: Poetry (рекомендуется)
+
+```bash
+# Установите poetry (если не установлен)
+curl -sSL https://install.python-poetry.org | python3 -
+
+# Установите зависимости
+poetry install
+
+# Активируйте виртуальное окружение
+poetry shell
+```
+
+### Вариант 2: pip (классический способ)
+
+```bash
+python -m venv venv
+source venv/bin/activate  # На Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## 🏃 Шаг 4: Запуск разработки
+
+### 4.1 Запустите локальный сервер
+
+```bash
+cd oknardia
+python manage.py runserver
+```
+
+Откройте браузер: **http://127.0.0.1:8000**
+
+### 4.2 Запустите задачи Celery (опционально)
+
+```bash
+celery -A oknardia worker -l info
+```
+
+## 📁 Шаг 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          # Проверка для продакшена
+```
+
+## 📚 Дополнительные ресурсы
+
+- [Django документация](https://docs.djangoproject.com/en/stable/)
+- [AGENTS.md](./AGENTS.md) — архитектура и конвенции проекта
+- [README.md](./README.md) — основная информация о проекте
+- [SECURITY_AUDIT_REPORT.md](./SECURITY_AUDIT_REPORT.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
+