mnemo_cards/tools/docs/CI_CD_SETUP.md

# Настройка CI/CD для проекта Mnemo Cards

Этот документ описывает настройку автоматической сборки, тестирования и развертывания проекта в Forgejo.

## Архитектура CI/CD

Проект использует многоуровневую архитектуру CI/CD с разделением на отдельные компоненты:

- **Backend** (Dart) - серверная часть
- **Web App** (Flutter Web) - веб версия приложения
- **Mobile App** (Flutter) - мобильное приложение для Android/iOS
- **Common Libraries** - общие пакеты

## Структура Workflow

```
tools/ci/
├── ci-main.yml           # Главный координирующий workflow
├── ci-backend.yml        # CI для backend
├── ci-web.yml           # CI для веб приложения
├── ci-mobile.yml        # CI для мобильного приложения
├── cd-deploy.yml        # CD для развертывания
├── code-quality.yml     # Контроль качества кода
├── release.yml          # Автоматические релизы
└── agent.yml           # AI-агент для автоматической генерации кода
```

## Требуемые Secrets

Для работы CI/CD необходимо настроить следующие секреты в Forgejo:

### SSH доступ для развертывания
```
DEPLOY_SSH_PRIVATE_KEY  # Приватный SSH ключ для доступа к серверу 147.45.152.129
```

### API ключи (опционально)
```
OPENAI_API_KEY          # Для AI-агента
```

## Настройка серверов

### Единый сервер (147.45.152.129)
- **API Backend** (api.memo-cards.online): Dart SDK, systemd сервис `mnemo_cards_server.service`
- **Web App** (memo-cards.online): Nginx, Flutter Web приложение
- **SSL**: Let's Encrypt сертификаты для обоих доменов
- **CORS**: Правильно настроен между доменами, COEP/COOP headers отключены для совместимости
- Доступ по SSH для деплоя

## Процесс CI/CD

### 1. Code Quality Gate
- Проверка линтинга для всех проектов
- Запуск тестов с покрытием
- Сканирование на наличие секретов
- Проверка зависимостей на уязвимости

### 2. Сборка компонентов
- **Backend**: Компиляция в нативный бинарный файл
- **Web App**: Сборка Flutter web приложения
- **Mobile App**: Сборка APK для Android и app для iOS

### 3. Развертывание
- **Backend**: Автоматическое обновление сервиса
- **Web App**: Rsync на веб сервер + перезагрузка Nginx
- **Mobile App**: Создание GitHub релиза с APK

## 🚀 Быстрый старт деплоя

### ✅ Чек-лист готовности

- [ ] **SSH ключ сгенерирован и добавлен на сервер**
- [ ] **DNS домены настроены** (`memo-cards.online`, `api.memo-cards.online`, `code.memo-cards.online`)
- [ ] **Forgejo secrets настроены** (`DEPLOY_SSH_PRIVATE_KEY`)
- [ ] **Код готов к деплою** (все тесты проходят)

### 🎯 Запуск в 3 шага

1. **Подготовка:**
   ```bash
   # Генерация и настройка SSH ключа
   ssh-keygen -t ed25519 -C "forgejo-deploy@memo-cards.online" -f ~/.ssh/forgejo_deploy
   ssh-copy-id -i ~/.ssh/forgejo_deploy.pub root@147.45.152.129
   ```

2. **Настройка Forgejo:**
   - Перейти в Settings → Secrets
   - Добавить `DEPLOY_SSH_PRIVATE_KEY` с содержимым `~/.ssh/forgejo_deploy`

3. **Запуск:**
   ```bash
   git push origin main  # Автоматический запуск CI/CD
   ```

## Запуск CI/CD

### 🔧 Предварительная настройка

#### 1. Настройка SSH доступа
```bash
# Генерация SSH ключа (если нет)
ssh-keygen -t ed25519 -C "forgejo-deploy@mnemo-cards.online" -f ~/.ssh/forgejo_deploy

# Копирование публичного ключа на сервер
ssh-copy-id -i ~/.ssh/forgejo_deploy.pub root@147.45.152.129

# Добавление приватного ключа в Forgejo secrets
# Settings → Secrets → DEPLOY_SSH_PRIVATE_KEY
cat ~/.ssh/forgejo_deploy
```

#### 2. Настройка DNS доменов
Убедитесь, что DNS записи настроены:
- `memo-cards.online` → `147.45.152.129`
- `api.memo-cards.online` → `147.45.152.129`
- `code.memo-cards.online` → `147.45.152.129` (для Forgejo)

#### 3. Проверка доступа к серверу
```bash
# Тест SSH подключения
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129 "echo 'SSH works!'"

# Проверка что Dart установлен
ssh root@147.45.152.129 "dart --version"

# Проверка что Nginx установлен
ssh root@147.45.152.129 "nginx -v"
```

### 🚀 Запуск деплоя

#### Автоматический запуск
CI/CD запускается автоматически при:
- Push в ветки `main`/`master`
- Создании Pull Request
- Создании тега релиза (`v*.*.*`)

#### Ручной запуск
1. Перейдите в раздел **Actions** в Forgejo
2. Выберите workflow **"Main CI Pipeline"**
3. Нажмите **"Run workflow"**

#### Ручной деплой (альтернатива)
```bash
# Деплой backend
tools/deploy/backend-build_app.sh

# Деплой web app
cd mnemo_cards_web_v2
tools/deploy/web-app/deploy.sh
```

## Мониторинг и логи

### Просмотр результатов
- Результаты тестов: `coverage/lcov.info`
- Логи сборки: В разделе Actions каждого workflow
- Артефакты сборки: Скачиваются из Actions

### Уведомления
При успешном/неуспешном завершении можно настроить уведомления через:
- Email
- Webhooks
- Forgejo notifications

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

### Автоматический релиз
1. Создайте git tag: `git tag v1.2.3 && git push origin v1.2.3`
2. Workflow автоматически:
   - Создаст GitHub release
   - Обновит версии в pubspec.yaml файлах
   - Опубликует APK и другие артефакты

### Ручной релиз
Используйте существующие скрипты:
```bash
./mnemo_cards_backend/build_app.sh    # Деплой backend
./mnemo_cards_web_v2/deploy/deploy.sh # Деплой web app
```

## Troubleshooting

### 🚨 Проблемы с деплоем

#### SSH подключение не работает
```bash
# Проверка SSH ключа локально
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129 "echo 'Connection OK'"

# Проверка что ключ добавлен в known_hosts
ssh-keyscan -H 147.45.152.129 >> ~/.ssh/known_hosts

# В Forgejo secrets должен быть полный приватный ключ
cat ~/.ssh/forgejo_deploy
```

#### Backend деплой падает
```bash
# Проверка что Dart установлен на сервере
ssh root@147.45.152.129 "which dart && dart --version"

# Ручной запуск build скрипта
tools/deploy/backend-build_app.sh

# Проверка статуса сервиса
ssh root@147.45.152.129 "systemctl status mnemo_cards_server"
```

#### Web app деплой падает
```bash
# Проверка что Nginx установлен
ssh root@147.45.152.129 "which nginx && nginx -v"

# Ручной запуск deploy скрипта
cd mnemo_cards_web_v2
tools/deploy/web-app/deploy.sh

# Проверка Nginx конфигурации
ssh root@147.45.152.129 "nginx -t"
```

#### SSL сертификаты не работают
```bash
# Проверка Let's Encrypt сертификатов
ssh root@147.45.152.129 "ls -la /etc/letsencrypt/live/"

# Ручное получение сертификатов
ssh root@147.45.152.129 "certbot certonly --standalone -d memo-cards.online -d api.memo-cards.online --email admin@memo-cards.online"
```

#### DNS проблемы
```bash
# Проверка DNS разрешения
nslookup memo-cards.online
nslookup api.memo-cards.online
nslookup code.memo-cards.online

# Проверка доступности портов
telnet 147.45.152.129 80
telnet 147.45.152.129 443
telnet 147.45.152.129 8080
telnet 147.45.152.129 8081
```

### Проблемы с зависимостями
```bash
# Очистка кэша
flutter clean
flutter pub cache repair
```

### Проблемы с SSH
```bash
# Проверка SSH ключа
ssh -T git@code.memo-cards.online

# Проверка доступа к серверам
ssh -i ~/.ssh/forgejo_deploy root@147.45.152.129
```

### Проблемы с тестами
```bash
# Запуск тестов локально
cd mnemo_cards_web_v2
flutter test --coverage

# Просмотр покрытия
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html
```

## Безопасность

### Защита секретов
- Никогда не коммитьте реальные ключи в код
- Используйте отдельные ключи для каждого окружения
- Регулярно ротируйте SSH ключи

### Code Quality Gates
- Минимальное покрытие тестами: 80%
- Обязательный проход линтера
- Сканирование на уязвимости в зависимостях

## Расширение CI/CD

### Добавление нового компонента
1. Создайте новый workflow файл в `.forgejo/workflows/`
2. Добавьте ссылку в `ci-main.yml`
3. Настройте необходимые секреты

### Кастомные проверки
Добавьте в `code-quality.yml`:
```yaml
- name: Custom check
  run: |
    # Ваша логика проверки
```

## Контакты

При проблемах с CI/CD:
1. Проверьте логи в Actions
2. Убедитесь, что все секреты настроены
3. Проверьте доступ к серверам
4. Создайте issue в репозитории