Skip to main content

CI/CD Setup

GitHub Actions для автогенерации документации, Dokploy webhooks для автодеплоя.

1. Как работает автодеплой​

Сервисы приложения (Backend, Frontend, Admin, etc.)​

Dokploy автоматически деплоит при push в main — настройка не требуется (включено по умолчанию при подключении Git).

Documentation (Docs Site)​

Docs Site — единственный сервис с отключённым автодеплоем. Он деплоится через GitHub Actions.

2. Watch Paths (что триггерит что)​

Изменённые файлыТриггерит деплой
backend/**Backend
frontend/**Frontend
admin/**Admin
shared/**Backend + Frontend + Admin
redirect-service/**Redirect Service
backend/prisma/**Backend + Redirect Service
static-nginx/**Static Nginx
monitoring/**Monitoring
docs-site/docs/**GitHub Actions → Docs Site

3. Настройка GitHub Actions​

3.1 Secrets​

В GitHub → Repository → Settings → Secrets and variables → Actions:

SecretОписаниеГде взять
SWAGGER_API_KEYAPI-ключ для SwaggerТот же, что в Backend env: SWAGGER_API_KEY
DOKPLOY_DOCS_WEBHOOKWebhook URL для деплоя docsDokploy UI → Docs Service → General → Deploy Webhook

3.2 Workflow файл​

Workflow уже в репозитории: .github/workflows/generate-docs.yml

Триггеры:

УсловиеДействие
Push в main с изменениями в backend/src/**/schemas/, backend/src/**/routes/, backend/src/server.tsFull rebuild (ждёт 5 мин Dokploy + OpenAPI fetch)
Push в main с изменениями в docs-site/docs/**/*.md, docs-site/docs/**/*.mdxQuick rebuild (без ожидания API)
Push в main с изменениями в docs-site/plugins/**, docusaurus.config.tsQuick rebuild
Manual workflow_dispatchFull rebuild (можно пропустить задержку)

3.3 Получение Webhook URL​

  1. Dokploy UI → Project "goLoot" → Service "docs-site"
  2. General → Deploy Webhook
  3. Скопировать URL
  4. Вставить в GitHub Secret DOKPLOY_DOCS_WEBHOOK

4. Ручная регенерация документации​

# Из GitHub UI:
# Actions → "Generate Documentation" → "Run workflow" → "Run"

Или через GitHub CLI:

gh workflow run generate-docs.yml

5. Первый деплой Docs Site​

При первом развёртывании ветки docs-build ещё нет. Нужно:

  1. Запустить workflow вручную (GitHub Actions → "Generate Documentation" → "Run workflow")
  2. Workflow создаст ветку docs-build и запушит сборку
  3. Dokploy задеплоит из этой ветки
Если workflow падает

Первый запуск может упасть, если Backend ещё не задеплоен (health check fails). В этом случае:

  1. Сначала задеплой Backend
  2. Убедись что https://api.goloot.online/health отвечает
  3. Перезапусти workflow

6. Критичные правила​

pnpm-lock.yaml​

Всегда коммитить вместе с package.json

pnpm-lock.yaml лежит в корне репозитория, но не в watch paths сервисов. Если изменить package.json без коммита pnpm-lock.yaml, билд упадёт:

ERR_PNPM_OUTDATED_LOCKFILE

Решение: Всегда коммитить pnpm-lock.yaml вместе с package.json.

shared/ — аккуратно с изменениями​

Изменения в shared/ триггерят деплой трёх сервисов:

  • Backend
  • Frontend
  • Admin

Breaking changes в типах могут сломать все три сборки одновременно.

Docs Auto Deploy = OFF​

Docs Site не деплоится автоматически по push в main. Только через webhook от GitHub Actions.

7. Мониторинг CI/CD​

GitHub Actions​

  • Repository → Actions → просмотр workflow runs
  • Статусы: Success, Failed, In Progress
  • Логи: клик на workflow run → детальные логи каждого шага

Dokploy​

  • Dokploy UI → Service → Deployments — история деплоев
  • Каждый деплой показывает: статус, время, логи сборки

8. Troubleshooting​

Workflow падает на "Fetch OpenAPI spec"​

Причина: Backend не доступен или SWAGGER_API_KEY неверный.

# Проверить вручную:
curl -H "X-API-Key: YOUR_SWAGGER_KEY" https://api.goloot.online/docs/json

Dokploy не деплоит после webhook​

  1. Проверить что Webhook URL корректный
  2. В Dokploy UI → Service → Deployments — есть ли новый деплой?
  3. Если нет — webhook мог не дойти. Перезапустить workflow.

Build падает с OOM​

Сборка Docusaurus может потреблять много RAM. Стандартный GitHub-hosted runner (ubuntu-latest) имеет 7 GB RAM — этого достаточно. На VPS с ограниченной памятью сборка может упасть с OOM.

Если нужно собрать локально на машине с малым объёмом RAM:

NODE_OPTIONS='--max-old-space-size=4096' pnpm --filter docs-site build

9. Чеклист​

  • GitHub Secrets настроены (SWAGGER_API_KEY, DOKPLOY_DOCS_WEBHOOK)
  • Первый запуск workflow выполнен
  • Ветка docs-build создана
  • Docs Site деплоится из docs-build
  • Auto Deploy для Docs Site выключен
  • Watch Paths настроены для остальных сервисов