From 37320684642afd59625539b4664ef293517a7ddb Mon Sep 17 00:00:00 2001 From: "Andrey K. Choi" Date: Tue, 4 Nov 2025 20:47:00 +0900 Subject: [PATCH] docs moved --- DEPLOYMENT.md | 323 ------------------ COMMANDS.md => docs/COMMANDS.md | 0 docs/DEPLOYMENT.md | 341 +++++++++++++++++--- PRODUCTION_FIX.md => docs/PRODUCTION_FIX.md | 0 SECURITY.md => docs/SECURITY.md | 0 5 files changed, 298 insertions(+), 366 deletions(-) delete mode 100644 DEPLOYMENT.md rename COMMANDS.md => docs/COMMANDS.md (100%) rename PRODUCTION_FIX.md => docs/PRODUCTION_FIX.md (100%) rename SECURITY.md => docs/SECURITY.md (100%) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md deleted file mode 100644 index d174fab..0000000 --- a/DEPLOYMENT.md +++ /dev/null @@ -1,323 +0,0 @@ -# 🚀 CatLink Master Deployment Guide - -Полное руководство по мастер-развертыванию проекта CatLink с автоматической настройкой всех компонентов. - -## 🎯 Что включает мастер-развертывание - -### 1. 🔧 Системные требования и подготовка -- Автоматическая проверка системы -- Установка необходимых компонентов (nginx, certbot, docker) -- Проверка портов и ресурсов - -### 2. ⚙️ Генерация конфигурации -- **Автоматическая генерация .env** с безопасными настройками -- **Генерация Django SECRET_KEY** (криптографически стойкий) -- **Генерация паролей БД** (32 символа, случайные) -- **Настройка доменов** и SSL параметров - -### 3. 🗄️ База данных и безопасность -- **Полная изоляция PostgreSQL** в Docker сети -- **Удаление прав суперпользователя** у приложения -- **SCRAM-SHA-256 аутентификация** -- **TLSv1.3 SSL/TLS** для БД -- **Детальное логирование** всех операций -- **Автоматический аудит безопасности** - -### 4. 🔒 SSL/TLS сертификаты -- **Let's Encrypt** автоматическое получение -- **Автообновление сертификатов** via cron -- **Fallback на самоподписанные** для тестирования -- **HTTP→HTTPS редирект** -- **Security headers** (HSTS, CSP, XSS Protection) - -### 5. 🌐 Nginx конфигурация -- **Reverse proxy** для frontend и backend -- **Security headers** и защита -- **Gzip compression** -- **Статические файлы** с кэшированием -- **Rate limiting** и DDoS защита - -### 6. 💾 Backup и мониторинг -- **Автоматические backup** БД и файлов -- **Система здоровья** (health checks) -- **Логирование** всех операций -- **Cron задачи** для обслуживания - -## 🚀 Быстрый старт - -### 1. Проверка готовности системы -```bash -make pre-deploy-check -``` - -### 2. Мастер-развертывание -```bash -make deploy -``` - -### 3. Проверка безопасности -```bash -make security-audit -``` - -## 📋 Пошаговая инструкция - -### Шаг 1: Подготовка сервера - -1. **Обновите систему:** -```bash -sudo apt update && sudo apt upgrade -y -``` - -2. **Клонируйте проект:** -```bash -cd /opt -sudo git clone https://github.com/smartsoltech/links.git -sudo chown -R $USER:$USER links -cd links -``` - -3. **Проверьте готовность:** -```bash -make pre-deploy-check -``` - -### Шаг 2: Настройка DNS - -Убедитесь что ваш домен указывает на IP сервера: -```bash -# Проверьте A-запись -nslookup your-domain.com - -# Должен возвращать IP вашего сервера -``` - -### Шаг 3: Мастер-развертывание - -Запустите мастер-скрипт: -```bash -make deploy -``` - -Скрипт запросит: -- **Основной домен** (например: links.yourdomain.com) -- **Дополнительные домены** (через запятую, опционально) -- **Email для Let's Encrypt** -- **Режим SSL** (Let's Encrypt / самоподписанный / без SSL) -- **Окружение** (production / staging / development) - -### Шаг 4: Проверка развертывания - -После завершения проверьте: -```bash -# Статус сервисов -make status - -# Проверка здоровья -./scripts/health-check.sh - -# Аудит безопасности -make security-audit -``` - -## 🔧 Генерируемые файлы и настройки - -### 1. `.env` файл -Автоматически генерируется с: -- **DJANGO_SECRET_KEY** - криптографически стойкий ключ -- **DATABASE_PASSWORD** - случайный 32-символьный пароль -- **DJANGO_ALLOWED_HOSTS** - настроенные домены -- **NEXT_PUBLIC_API_URL** - правильный API URL -- **SSL настройки** в зависимости от выбора - -### 2. Nginx конфигурация -- **HTTP→HTTPS редирект** -- **Security headers** (HSTS, CSP, XSS Protection) -- **Proxy настройки** для frontend и backend -- **Gzip compression** -- **Timeout настройки** - -### 3. PostgreSQL безопасность -- **Изоляция в Docker сети** (без внешних портов) -- **SCRAM-SHA-256** аутентификация -- **TLSv1.3** для SSL -- **Логирование** подключений и операций -- **Ограниченные права** для пользователя приложения - -### 4. SSL сертификаты -- **Let's Encrypt** с автообновлением -- **Wildcard поддержка** для поддоменов -- **Fallback** на самоподписанные -- **Cron задача** для обновления - -## 🔒 Безопасность - -### Аудит безопасности PostgreSQL -```bash -make security-audit -``` - -**Проверяет:** -- Версию PostgreSQL -- SSL настройки -- Права пользователей -- Сетевую изоляцию -- Настройки логирования -- Конфигурационные файлы - -**Оценивает по 10-балльной шкале** - -### Управление SSL -```bash -# Интерактивная настройка SSL -make ssl-setup - -# Обновление сертификатов -make ssl-renew -``` - -### Обновление безопасности в продакшене -```bash -make update-production-security -``` - -## 💾 Backup и восстановление - -### Автоматические backup -- **База данных**: ежедневно в 2:00 -- **Файлы**: tar.gz архивы -- **Конфигурация**: .env и docker-compose файлы -- **Ротация**: хранение 30 дней - -### Ручной backup -```bash -./scripts/auto-backup.sh -``` - -### Восстановление -```bash -# Восстановление БД -docker exec -i links-db-1 psql -U postgres links_db < backups/database/links_db_YYYYMMDD_HHMMSS.sql - -# Восстановление файлов -tar -xzf backups/files/media_YYYYMMDD_HHMMSS.tar.gz -``` - -## 📊 Мониторинг и обслуживание - -### Проверка здоровья системы -```bash -./scripts/health-check.sh -``` - -### Просмотр логов -```bash -make logs -``` - -### Мониторинг ресурсов -```bash -make monitor -``` - -### Перезапуск сервисов -```bash -make restart -``` - -## 🆘 Устранение неполадок - -### 1. Проблемы с SSL -```bash -# Проверка статуса сертификатов -./scripts/ssl-manager.sh - -# Принудительное обновление -sudo certbot renew --force-renewal -``` - -### 2. Проблемы с БД -```bash -# Аудит безопасности -make security-audit - -# Проверка подключения -docker exec links-db-1 pg_isready -U postgres -``` - -### 3. Проблемы с контейнерами -```bash -# Пересборка без кэша -make build - -# Полный перезапуск -make restart - -# Просмотр логов -make logs -``` - -### 4. Проблемы с доменом -```bash -# Проверка DNS -nslookup your-domain.com - -# Проверка nginx -sudo nginx -t -sudo systemctl status nginx -``` - -## 🎯 Результат развертывания - -После успешного развертывания вы получите: - -### 🌐 Готовый сайт -- **HTTPS** с валидными сертификатами -- **Автообновление** SSL -- **Security headers** и защита -- **Optimized** конфигурация nginx - -### 🔒 Безопасная БД -- **Изолированная** в Docker сети -- **Зашифрованные** соединения (TLS 1.3) -- **Ограниченные права** приложения -- **Полное логирование** - -### 💾 Система backup -- **Автоматические** ежедневные backup -- **Ротация** файлов (30 дней) -- **Простое восстановление** - -### 📊 Мониторинг -- **Health checks** для всех сервисов -- **Логирование** операций -- **Resource monitoring** - -## 🔄 Обновления - -### Обновление кода -```bash -git pull -make restart -``` - -### Обновление безопасности -```bash -make update-production-security -``` - -### Обновление SSL -```bash -make ssl-renew -``` - -## 📞 Поддержка - -- **README.md** - основная документация -- **SECURITY.md** - руководство по безопасности -- **logs/** - логи системы -- **scripts/** - утилиты обслуживания - ---- - -**🎉 Поздравляем! Ваш CatLink готов к использованию!** \ No newline at end of file diff --git a/COMMANDS.md b/docs/COMMANDS.md similarity index 100% rename from COMMANDS.md rename to docs/COMMANDS.md diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 2e9f765..d174fab 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -1,68 +1,323 @@ -# Переменные окружения +# 🚀 CatLink Master Deployment Guide -Скопируйте `.env.example` в `.env` и настройте следующие переменные: +Полное руководство по мастер-развертыванию проекта CatLink с автоматической настройкой всех компонентов. -## Django настройки -- `DJANGO_SECRET_KEY` - Секретный ключ Django (обязательно изменить в продакшене) -- `DJANGO_DEBUG` - Режим отладки (True/False) -- `DJANGO_ALLOWED_HOSTS` - Разрешенные хосты (разделенные запятыми) +## 🎯 Что включает мастер-развертывание -## База данных PostgreSQL -- `DATABASE_ENGINE` - Движок базы данных (django.db.backends.postgresql) -- `DATABASE_NAME` - Название базы данных -- `DATABASE_USER` - Пользователь базы данных -- `DATABASE_PASSWORD` - Пароль базы данных -- `DATABASE_HOST` - Хост базы данных (db для Docker) -- `DATABASE_PORT` - Порт базы данных (5432) +### 1. 🔧 Системные требования и подготовка +- Автоматическая проверка системы +- Установка необходимых компонентов (nginx, certbot, docker) +- Проверка портов и ресурсов -## PostgreSQL настройки для контейнера -- `POSTGRES_DB` - Название БД для создания в контейнере -- `POSTGRES_USER` - Пользователь БД для создания в контейнере -- `POSTGRES_PASSWORD` - Пароль пользователя БД в контейнере +### 2. ⚙️ Генерация конфигурации +- **Автоматическая генерация .env** с безопасными настройками +- **Генерация Django SECRET_KEY** (криптографически стойкий) +- **Генерация паролей БД** (32 символа, случайные) +- **Настройка доменов** и SSL параметров -## Frontend настройки -- `NEXT_PUBLIC_API_URL` - URL API для frontend (http://localhost:8000) +### 3. 🗄️ База данных и безопасность +- **Полная изоляция PostgreSQL** в Docker сети +- **Удаление прав суперпользователя** у приложения +- **SCRAM-SHA-256 аутентификация** +- **TLSv1.3 SSL/TLS** для БД +- **Детальное логирование** всех операций +- **Автоматический аудит безопасности** -## Команды для запуска +### 4. 🔒 SSL/TLS сертификаты +- **Let's Encrypt** автоматическое получение +- **Автообновление сертификатов** via cron +- **Fallback на самоподписанные** для тестирования +- **HTTP→HTTPS редирект** +- **Security headers** (HSTS, CSP, XSS Protection) -### Подготовка +### 5. 🌐 Nginx конфигурация +- **Reverse proxy** для frontend и backend +- **Security headers** и защита +- **Gzip compression** +- **Статические файлы** с кэшированием +- **Rate limiting** и DDoS защита + +### 6. 💾 Backup и мониторинг +- **Автоматические backup** БД и файлов +- **Система здоровья** (health checks) +- **Логирование** всех операций +- **Cron задачи** для обслуживания + +## 🚀 Быстрый старт + +### 1. Проверка готовности системы ```bash -cp .env.example .env -# Отредактируйте .env файл при необходимости +make pre-deploy-check ``` -### Запуск всех сервисов +### 2. Мастер-развертывание ```bash -make up # или docker-compose up -d --build +make deploy ``` -### Применение миграций +### 3. Проверка безопасности ```bash -make migrate # или docker-compose exec web python manage.py migrate +make security-audit ``` -### Остановка сервисов +## 📋 Пошаговая инструкция + +### Шаг 1: Подготовка сервера + +1. **Обновите систему:** ```bash -make down # или docker-compose down +sudo apt update && sudo apt upgrade -y ``` -### Запуск тестов +2. **Клонируйте проект:** ```bash -make test # или docker-compose exec web pytest --maxfail=1 --disable-warnings -q +cd /opt +sudo git clone https://github.com/smartsoltech/links.git +sudo chown -R $USER:$USER links +cd links ``` -## Доступ к сервисам +3. **Проверьте готовность:** +```bash +make pre-deploy-check +``` -- **Frontend**: http://localhost:3000 -- **Backend API**: http://localhost:8000/api/ -- **Django Admin**: http://localhost:8000/admin/ -- **PostgreSQL**: localhost:5432 +### Шаг 2: Настройка DNS -## Структура проекта +Убедитесь что ваш домен указывает на IP сервера: +```bash +# Проверьте A-запись +nslookup your-domain.com -- `backend/` - Django приложение -- `frontend/linktree-frontend/` - Next.js приложение -- `.env` - Переменные окружения (не включается в git) -- `.env.example` - Пример переменных окружения -- `docker-compose.yml` - Конфигурация Docker Compose -- `Makefile` - Команды для удобного управления \ No newline at end of file +# Должен возвращать IP вашего сервера +``` + +### Шаг 3: Мастер-развертывание + +Запустите мастер-скрипт: +```bash +make deploy +``` + +Скрипт запросит: +- **Основной домен** (например: links.yourdomain.com) +- **Дополнительные домены** (через запятую, опционально) +- **Email для Let's Encrypt** +- **Режим SSL** (Let's Encrypt / самоподписанный / без SSL) +- **Окружение** (production / staging / development) + +### Шаг 4: Проверка развертывания + +После завершения проверьте: +```bash +# Статус сервисов +make status + +# Проверка здоровья +./scripts/health-check.sh + +# Аудит безопасности +make security-audit +``` + +## 🔧 Генерируемые файлы и настройки + +### 1. `.env` файл +Автоматически генерируется с: +- **DJANGO_SECRET_KEY** - криптографически стойкий ключ +- **DATABASE_PASSWORD** - случайный 32-символьный пароль +- **DJANGO_ALLOWED_HOSTS** - настроенные домены +- **NEXT_PUBLIC_API_URL** - правильный API URL +- **SSL настройки** в зависимости от выбора + +### 2. Nginx конфигурация +- **HTTP→HTTPS редирект** +- **Security headers** (HSTS, CSP, XSS Protection) +- **Proxy настройки** для frontend и backend +- **Gzip compression** +- **Timeout настройки** + +### 3. PostgreSQL безопасность +- **Изоляция в Docker сети** (без внешних портов) +- **SCRAM-SHA-256** аутентификация +- **TLSv1.3** для SSL +- **Логирование** подключений и операций +- **Ограниченные права** для пользователя приложения + +### 4. SSL сертификаты +- **Let's Encrypt** с автообновлением +- **Wildcard поддержка** для поддоменов +- **Fallback** на самоподписанные +- **Cron задача** для обновления + +## 🔒 Безопасность + +### Аудит безопасности PostgreSQL +```bash +make security-audit +``` + +**Проверяет:** +- Версию PostgreSQL +- SSL настройки +- Права пользователей +- Сетевую изоляцию +- Настройки логирования +- Конфигурационные файлы + +**Оценивает по 10-балльной шкале** + +### Управление SSL +```bash +# Интерактивная настройка SSL +make ssl-setup + +# Обновление сертификатов +make ssl-renew +``` + +### Обновление безопасности в продакшене +```bash +make update-production-security +``` + +## 💾 Backup и восстановление + +### Автоматические backup +- **База данных**: ежедневно в 2:00 +- **Файлы**: tar.gz архивы +- **Конфигурация**: .env и docker-compose файлы +- **Ротация**: хранение 30 дней + +### Ручной backup +```bash +./scripts/auto-backup.sh +``` + +### Восстановление +```bash +# Восстановление БД +docker exec -i links-db-1 psql -U postgres links_db < backups/database/links_db_YYYYMMDD_HHMMSS.sql + +# Восстановление файлов +tar -xzf backups/files/media_YYYYMMDD_HHMMSS.tar.gz +``` + +## 📊 Мониторинг и обслуживание + +### Проверка здоровья системы +```bash +./scripts/health-check.sh +``` + +### Просмотр логов +```bash +make logs +``` + +### Мониторинг ресурсов +```bash +make monitor +``` + +### Перезапуск сервисов +```bash +make restart +``` + +## 🆘 Устранение неполадок + +### 1. Проблемы с SSL +```bash +# Проверка статуса сертификатов +./scripts/ssl-manager.sh + +# Принудительное обновление +sudo certbot renew --force-renewal +``` + +### 2. Проблемы с БД +```bash +# Аудит безопасности +make security-audit + +# Проверка подключения +docker exec links-db-1 pg_isready -U postgres +``` + +### 3. Проблемы с контейнерами +```bash +# Пересборка без кэша +make build + +# Полный перезапуск +make restart + +# Просмотр логов +make logs +``` + +### 4. Проблемы с доменом +```bash +# Проверка DNS +nslookup your-domain.com + +# Проверка nginx +sudo nginx -t +sudo systemctl status nginx +``` + +## 🎯 Результат развертывания + +После успешного развертывания вы получите: + +### 🌐 Готовый сайт +- **HTTPS** с валидными сертификатами +- **Автообновление** SSL +- **Security headers** и защита +- **Optimized** конфигурация nginx + +### 🔒 Безопасная БД +- **Изолированная** в Docker сети +- **Зашифрованные** соединения (TLS 1.3) +- **Ограниченные права** приложения +- **Полное логирование** + +### 💾 Система backup +- **Автоматические** ежедневные backup +- **Ротация** файлов (30 дней) +- **Простое восстановление** + +### 📊 Мониторинг +- **Health checks** для всех сервисов +- **Логирование** операций +- **Resource monitoring** + +## 🔄 Обновления + +### Обновление кода +```bash +git pull +make restart +``` + +### Обновление безопасности +```bash +make update-production-security +``` + +### Обновление SSL +```bash +make ssl-renew +``` + +## 📞 Поддержка + +- **README.md** - основная документация +- **SECURITY.md** - руководство по безопасности +- **logs/** - логи системы +- **scripts/** - утилиты обслуживания + +--- + +**🎉 Поздравляем! Ваш CatLink готов к использованию!** \ No newline at end of file diff --git a/PRODUCTION_FIX.md b/docs/PRODUCTION_FIX.md similarity index 100% rename from PRODUCTION_FIX.md rename to docs/PRODUCTION_FIX.md diff --git a/SECURITY.md b/docs/SECURITY.md similarity index 100% rename from SECURITY.md rename to docs/SECURITY.md