Skip to main content

Docs Deployment

1. Summary​

Goal: Автоматическая сборка и деплой документации без нагрузки на VPS. Вся тяжёлая webpack-компиляция происходит в GitHub Actions.

User Value: Push в main → через 2-7 минут изменения на docs.goloot.online. Никаких ручных действий, никакого OOM на сервере.

2. How It Works​

Deployment Paths​

Триггер: Изменение .md/.mdx файлов в docs-site/docs/

Что происходит:

  1. GitHub Actions запускается
  2. Сборка статики (pnpm docusaurus build)
  3. Коммит docs-site/build/ в репозиторий
  4. Webhook триггерит Dokploy
  5. Dokploy деплоит nginx с готовыми файлами

Пропускается: Ожидание backend, генерация OpenAPI

Trigger Paths​

ПаттернТип сборкиВремя
backend/src/**/schemas/**Full (OpenAPI)~7 min
backend/src/**/routes/**Full (OpenAPI)~7 min
backend/src/server.tsFull (OpenAPI)~7 min
docs-site/docs/**/*.mdQuick~2 min
docs-site/docs/**/*.mdxQuick~2 min
docs-site/plugins/**Quick~2 min
docs-site/docusaurus.config.tsQuick~2 min
docs-site/sidebars-*.tsQuick~2 min
Visibility Plugin

docusaurus-plugin-visibility.ts собирает visibility: owner frontmatter при сборке. Новые owner-only файлы появятся в sidebar только после пересборки.

What Gets Committed​

АртефактКогда коммититсяКудаОписание
docs-site/build/Всегдаdocs-build branchГотовая статика для nginx
docs-site/api-docs/При изменении backenddocs-build branchСгенерированные MDX
docs-site/specs/openapi.jsonПри изменении backenddocs-build branchСнапшот спецификации
Почему отдельная ветка?

Сгенерированные файлы пушатся в ветку docs-build, а не в main. Это предотвращает конфликты при push от разработчиков — main остаётся чистым.

Изоляция веток

Локально: Все разработчики и агенты работают только в main. Переключаться на docs-build не нужно.

docs-build ветка:

  • Существует только на remote (GitHub)
  • Создаётся и обновляется только GitHub Actions
  • Используется только Dokploy для деплоя

Это исключает конфликты при параллельной работе нескольких агентов/разработчиков.

3. ADR (Architectural Decisions)​

Почему Pre-built Assets?​

Проблема: Сборка Docusaurus требует ~4GB RAM и много CPU. VPS может иметь ограниченные ресурсы.

Решение: Билдим в GitHub Actions (7GB RAM, fast CPU), коммитим готовую статику.

Альтернативы (отклонены):

  • Сборка на VPS — риск OOM, медленно
  • Docker multi-stage build — всё равно нужен RAM на сборку

Последствия:

  • Репозиторий содержит build/ папку (~50MB)
  • Dockerfile просто копирует файлы в nginx
  • Нет зависимости от ресурсов VPS

Почему 5 минут ожидания?​

Проблема: GitHub Actions триггерится одновременно с Dokploy. Нужно дождаться деплоя backend.

Решение: Фиксированная задержка 5 минут + polling health check.

Альтернативы (отклонены):

  • Webhook от Dokploy → GitHub — сложная настройка
  • Только polling без задержки — много лишних запросов

Последствия: Надёжно, но увеличивает время full-цикла на 5 минут.

Почему не Dokploy webhook?

Dokploy может отправлять webhook при завершении деплоя, но:

  1. Требует настройки GitHub App или Personal Access Token
  2. Сложнее дебажить
  3. GitHub Actions нельзя триггерить через обычный HTTP webhook

Простая задержка + polling работает надёжно.

Почему Webhook для Docs деплоя?​

Проблема: Dokploy Autodeploy триггерится на ЛЮБОЙ push, но нам нужен деплой только после сборки.

Решение: Autodeploy выключен для docs-site. GitHub Actions вызывает webhook после успешной сборки.

Последствия: Контролируемый деплой, но требует настройки секрета DOKPLOY_DOCS_WEBHOOK.

4. Architecture​

Backend API Change Flow​

Docs Content Change Flow​

Infrastructure Components​

КомпонентРольURL
GitHub ActionsСборка, генерация.github/workflows/generate-docs.yml
Dokploy (backend)Autodeploy backendapi.goloot.online
Dokploy (docs)Deploy по webhookdocs.goloot.online
nginxРаздача статикиВнутри docs container

5. Configuration​

GitHub Secrets​

SecretНазначениеКак получить
DOKPLOY_DOCS_WEBHOOKТриггер деплоя docsDokploy → Docs Service → Deployments → Webhook URL
SWAGGER_API_KEYДоступ к /docs/jsonПеременная SWAGGER_API_KEY в backend

Dokploy: Backend Service​

ПараметрЗначение
Repositorygithub.com/gosystems25/goLoot
Branchmain
Dockerfile Pathbackend/Dockerfile
AutodeployON

Dokploy: Docs Service​

ПараметрЗначение
Repositorygithub.com/gosystems25/goLoot
Branchdocs-build ⚠️
Dockerfile Pathdocs-site/Dockerfile
Build Context/ (корень репозитория)
AutodeployOFF (через webhook)
Важно: ветка docs-build

Dokploy должен деплоить из ветки docs-build, а не main. В этой ветке находятся pre-built артефакты.

Domain Configuration​

ПолеЗначение
Hostdocs.goloot.online
Port80
HTTPSLet's Encrypt

6. Operations​

Manual Regeneration​

  1. GitHub → Actions → Build Docs Site
  2. Click "Run workflow"
  3. Check "Skip deployment wait" if backend already deployed
  4. Click "Run workflow"

Force Redeploy​

Dokploy → Docs Service → Deploy

Troubleshooting​

Причина: Container не запущен или неправильный порт

Решение:

  1. Dokploy → Logs — проверить ошибки
  2. Domains → убедиться Port = 80
  3. Terminal → ls -la /usr/share/nginx/html/
Workflow File Location
.github/workflows/generate-docs.yml

Ключевые шаги:

  • Check if backend API changed — определяет тип сборки
  • Wait for Dokploy deployment — 5 мин ожидание (условно)
  • Fetch OpenAPI spec — получение спецификации (условно)
  • Build static site — всегда
  • Trigger Dokploy docs deployment — webhook

7. File Structure​

docs-site/
├── Dockerfile              # Простой nginx, раздающий готовые файлы
├── build/                  # Собранная статика (коммитится GitHub Actions)
├── api-docs/               # Сгенерированные MDX из OpenAPI
├── specs/
│   └── openapi.json        # Снапшот OpenAPI спецификации
├── docs/
│   └── knowledge-base/     # Ручная документация
├── plugins/
│   └── docusaurus-plugin-visibility.ts
└── docusaurus.config.ts