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. Подготовка:

   # Генерация и настройка 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. Запуск:

   git push origin main  # Автоматический запуск CI/CD
   

Запуск CI/CD

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

1. Настройка SSH доступа

# Генерация 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. Проверка доступа к серверу

# Тест 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"

Ручной деплой (альтернатива)

# Деплой 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 и другие артефакты

Ручной релиз

Используйте существующие скрипты:

./mnemo_cards_backend/build_app.sh    # Деплой backend
./mnemo_cards_web_v2/deploy/deploy.sh # Деплой web app

Troubleshooting

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

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

# Проверка 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 деплой падает

# Проверка что 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 деплой падает

# Проверка что 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 сертификаты не работают

# Проверка 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 проблемы

# Проверка 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 8443
telnet 147.45.152.129 8081

Проблемы с зависимостями

# Очистка кэша
flutter clean
flutter pub cache repair

Проблемы с SSH

# Проверка SSH ключа
ssh -T git@code.memo-cards.online

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

Проблемы с тестами

# Запуск тестов локально
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:

- name: Custom check
  run: |
    # Ваша логика проверки    

Контакты

При проблемах с CI/CD:

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