links/docs/CICD.md

CI/CD Documentation

📋 Содержание

1. Обзор CI/CD
2. Архитектура пайплайна
3. Настройка Drone CI
4. Конфигурация окружений
5. Локальное тестирование
6. Деплой и управление
7. Мониторинг и уведомления
8. Устранение неполадок

🚀 Обзор CI/CD

CatLink использует современный CI/CD пайплайн на базе Drone CI для автоматизации:

• 🔍 Проверка качества кода (линтинг, форматирование)
• 🧪 Автоматизированное тестирование
• 🔒 Сканирование безопасности
• 🏗️ Сборка Docker образов
• 📤 Публикация в registry
• 🚀 Автоматический деплой на staging и production

Основные преимущества

• ✅ Автоматизация всех этапов развертывания
• ✅ Качество кода обеспечивается проверками
• ✅ Безопасность через сканирование уязвимостей
• ✅ Надежность благодаря тестированию
• ✅ Скорость развертывания изменений

🏗️ Архитектура пайплайна

Этапы CI/CD пайплайна

graph TD
    A[Git Push] --> B[Prepare]
    B --> C[Lint & Code Quality]
    C --> D[Build & Test]
    D --> E[Security Scan]
    E --> F[Build Production]
    F --> G[Publish Images]
    G --> H[Deploy Staging]
    H --> I[Deploy Production]
    I --> J[Notifications]

1. Prepare - Подготовка

• Настройка окружения
• Установка зависимостей
• Инициализация кэша

2. Lint - Проверка качества кода

• Python: flake8, black, isort
• TypeScript: ESLint, Prettier
• Docker: hadolint
• YAML: yamllint
• Security: bandit, safety

3. Build & Test - Сборка и тестирование

• Сборка Docker образов
• Запуск unit тестов
• API тестирование
• Frontend тесты
• Integration тесты

4. Security Scan - Проверка безопасности

• Сканирование зависимостей
• Анализ исходного кода
• Проверка Docker образов
• Аудит конфигураций

5. Build Production - Продакшен сборка

• Оптимизированные образы
• Multi-stage builds
• Минимальные базовые образы
• Метаданные и лейблы

6. Publish - Публикация

• Push в Docker registry
• Создание release notes
• Версионирование
• Уведомления команды

7. Deploy - Развертывание

• Staging деплой для тестирования
• Production деплой с проверками
• Rolling updates без простоя
• Health checks

🛠️ Настройка Drone CI

Требования

• Drone CI сервер
• Docker registry (Docker Hub, GitLab Registry, etc.)
• SSH доступ к серверам
• Переменные окружения

Переменные окружения

Обязательные переменные

# Docker Registry
DOCKER_REGISTRY=registry.hub.docker.com
DOCKER_USERNAME=your_username
DOCKER_PASSWORD=your_password

# Staging Environment
STAGING_HOST=staging.catlink.dev
STAGING_SSH_KEY=base64_encoded_ssh_key
STAGING_USER=deploy

# Production Environment
PRODUCTION_HOST=catlink.dev
PRODUCTION_SSH_KEY=base64_encoded_ssh_key
PRODUCTION_USER=deploy
PRODUCTION_SECRET_KEY=super_secret_key
PRODUCTION_POSTGRES_PASSWORD=secure_db_password
PRODUCTION_EMAIL_HOST=smtp.gmail.com
PRODUCTION_EMAIL_USER=your_email@gmail.com
PRODUCTION_EMAIL_PASSWORD=your_app_password

Дополнительные переменные

# Notifications
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

# Monitoring
SENTRY_DSN=https://...@sentry.io/...
PRODUCTION_SENTRY_DSN=https://...@sentry.io/...
GOOGLE_ANALYTICS_ID=GA_MEASUREMENT_ID

# Backup
PRODUCTION_BACKUP_S3_BUCKET=catlink-backups

Настройка SSH ключей

1. Генерация SSH ключа:

ssh-keygen -t rsa -b 4096 -C "deploy@catlink.dev" -f deploy_key

2. Кодирование в base64:

cat deploy_key | base64 -w 0

3. Добавление публичного ключа на сервер:

cat deploy_key.pub >> ~/.ssh/authorized_keys

⚙️ Конфигурация окружений

Staging окружение

Цель: Тестирование новых функций и изменений

Характеристики:

• Автоматический деплой с main ветки
• Тестовые данные
• Менее строгие проверки безопасности
• Быстрое развертывание

URL: https://staging.catlink.dev

Production окружение

Цель: Рабочее приложение для пользователей

Характеристики:

• Деплой только с тегов версий
• Строгие проверки безопасности
• Резервные копии перед деплоем
• Rolling deployment без простоя
• Полный мониторинг

URL: https://catlink.dev

🧪 Локальное тестирование

Make команды для CI/CD

# Проверка качества кода
make ci-lint

# Запуск тестов
make ci-test

# Проверка безопасности
make ci-security

# Локальная сборка
make ci-build

# Полный пайплайн
make ci-pipeline

# Валидация Drone конфигурации
make drone-validate

Ручной запуск скриптов

# Проверка кода
./scripts/ci/lint.sh

# Тестирование
./scripts/ci/test.sh

# Сканирование безопасности
./scripts/ci/security-scan.sh

# Сборка
./scripts/ci/build.sh

# Продакшен сборка
./scripts/ci/build-production.sh

Тестирование Docker образов

# Сборка и тестирование
docker build -t catlink-backend:test backend/
docker build -t catlink-frontend:test frontend/linktree-frontend/

# Запуск для тестирования
docker run -d -p 8001:8000 --name test-backend catlink-backend:test
docker run -d -p 3001:3000 --name test-frontend catlink-frontend:test

# Проверка работоспособности
curl http://localhost:8001/api/
curl http://localhost:3001/

# Очистка
docker stop test-backend test-frontend
docker rm test-backend test-frontend

🚀 Деплой и управление

Автоматический деплой

Staging деплой:

• Триггер: Push в main ветку
• Время: ~10-15 минут
• Проверки: Линтинг, тесты, безопасность

Production деплой:

• Триггер: Создание тега v*.*.*
• Время: ~20-30 минут
• Проверки: Полная валидация + ручные проверки

Ручной деплой

# Staging
make ci-deploy-staging

# Production (осторожно!)
make ci-deploy-production

Создание релиза

# Создание тега для production деплоя
git tag v1.2.3
git push origin v1.2.3

# Drone автоматически запустит production деплой

Откат изменений

# SSH на сервер
ssh production

# Откат к предыдущей версии
cd /opt/catlink
./manage-production.sh restore /opt/catlink/backups/backup-production-YYYYMMDD-HHMMSS.sql.gz

# Или через Docker образы
docker-compose -f docker-compose.production.yml down
# Измените версию в docker-compose.production.yml
docker-compose -f docker-compose.production.yml up -d

📊 Мониторинг и уведомления

Health checks

Автоматические проверки:

• API доступность (/api/health/)
• Frontend загрузка (/)
• Database подключение
• Redis доступность

Мониторинг производительности:

# Статус сервисов
./manage-production.sh status

# Проверка здоровья
./manage-production.sh health

# Мониторинг ресурсов
./monitor-production.sh

Уведомления

Slack интеграция:

# Настройка в Drone secrets
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Discord интеграция:

# Настройка в Drone secrets
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Email уведомления:

• Критические ошибки деплоя
• Проблемы с безопасностью
• Завершение деплоя в production

Логи и мониторинг

# Просмотр логов деплоя
ssh production
cd /opt/catlink
./manage-production.sh logs

# Мониторинг в реальном времени
./monitor-production.sh

# Логи конкретного сервиса
./manage-production.sh logs web
./manage-production.sh logs frontend

🔧 Устранение неполадок

Частые проблемы

1. Ошибка аутентификации Docker registry

Проблема: Error response from daemon: pull access denied

Решение:

# Проверьте переменные
echo $DOCKER_USERNAME
echo $DOCKER_PASSWORD

# Перелогиньтесь
docker logout
docker login

2. SSH подключение не работает

Проблема: Permission denied (publickey)

Решение:

# Проверьте SSH ключ
ssh-keygen -y -f ~/.ssh/id_rsa

# Проверьте формат в Drone
cat ~/.ssh/id_rsa | base64 -w 0

# Добавьте ключ на сервер
ssh-copy-id user@server

3. Деплой завис

Проблема: Деплой не завершается

Решение:

# Проверьте статус контейнеров
docker-compose ps

# Проверьте логи
docker-compose logs

# Перезапустите сервисы
docker-compose restart

# В крайнем случае - полный перезапуск
docker-compose down
docker-compose up -d

4. Тесты падают в CI

Проблема: Тесты проходят локально, но падают в CI

Решение:

# Запустите тесты локально как в CI
make ci-test

# Проверьте переменные окружения
env | grep -E "(TEST_|CI_|DJANGO_)"

# Проверьте зависимости
pip list
npm list

Отладка Drone пайплайна

# Валидация конфигурации
make drone-validate

# Локальный запуск
drone exec

# Просмотр логов
drone build ls smartsoltech/links
drone build logs smartsoltech/links <build_number>

Откат деплоя

# 1. Быстрый откат через Docker
docker tag catlink-backend:previous catlink-backend:latest
docker tag catlink-frontend:previous catlink-frontend:latest
docker-compose up -d

# 2. Откат через бэкап
./manage-production.sh restore backup-file.sql.gz

# 3. Откат к конкретной версии
# Измените версию в docker-compose.production.yml
# Перезапустите сервисы

Контакты для поддержки

• Email: support@catlink.dev
• Slack: #devops-support
• Документация: docs/
• Issues: GitHub Issues

---

📚 Дополнительные ресурсы

• Drone CI Documentation
• Docker Best Practices
• Django Deployment
• Next.js Deployment
• Docker Security

Последнее обновление: $(date)
Версия документации: 1.0