# CI/CD Documentation

## 📋 Содержание

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

## 🚀 Обзор CI/CD

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

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

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

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

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

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

```mermaid
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 доступ к серверам
- Переменные окружения

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

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

```bash
# 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
```

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

```bash
# 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 ключа**:
```bash
ssh-keygen -t rsa -b 4096 -C "deploy@catlink.dev" -f deploy_key
```

2. **Кодирование в base64**:
```bash
cat deploy_key | base64 -w 0
```

3. **Добавление публичного ключа на сервер**:
```bash
cat deploy_key.pub >> ~/.ssh/authorized_keys
```

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

### Staging окружение

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

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

**URL**: `https://staging.catlink.dev`

### Production окружение

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

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

**URL**: `https://catlink.dev`

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```bash
# Сборка и тестирование
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 минут
- Проверки: Полная валидация + ручные проверки

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

```bash
# Staging
make ci-deploy-staging

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

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

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

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

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

```bash
# 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 доступность

**Мониторинг производительности**:
```bash
# Статус сервисов
./manage-production.sh status

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

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

### Уведомления

**Slack интеграция**:
```bash
# Настройка в Drone secrets
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
```

**Discord интеграция**:
```bash
# Настройка в Drone secrets
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
```

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

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

```bash
# Просмотр логов деплоя
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`

**Решение**:
```bash
# Проверьте переменные
echo $DOCKER_USERNAME
echo $DOCKER_PASSWORD

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

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

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

**Решение**:
```bash
# Проверьте SSH ключ
ssh-keygen -y -f ~/.ssh/id_rsa

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

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

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

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

**Решение**:
```bash
# Проверьте статус контейнеров
docker-compose ps

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

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

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

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

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

**Решение**:
```bash
# Запустите тесты локально как в CI
make ci-test

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

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

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

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

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

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

### Откат деплоя

```bash
# 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/](./README.md)
- **Issues**: GitHub Issues

---

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

- [Drone CI Documentation](https://docs.drone.io/)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
- [Django Deployment](https://docs.djangoproject.com/en/stable/howto/deployment/)
- [Next.js Deployment](https://nextjs.org/docs/deployment)
- [Docker Security](https://docs.docker.com/engine/security/)

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