EvoBGP/docs/quickstart.md

Быстрый запуск

Примеры команд для PowerShell. Репозиторий: корень EvoBGP, Docker Compose лежит в deploy\compose.

Требования

• Docker с поддержкой Compose v2 — для готового стека.
• Go 1.22+ (версию см. в go.mod) — для локального запуска бинарников из исходников.
• Node.js и npm — для разработки веб-интерфейса в web/.
• PostgreSQL — если запускаете API вне Compose; строка подключения в EVOBGP_DATABASE_URL.

Готовые образы без сборки (Container Registry Gitea)

После успешного CI (push в main или master) образы публикуются в Container Registry вашего Gitea. В workflow зафиксирован хост реестра git.shts.su; имя владельца в пути образа — в нижнем регистре, как у github.repository_owner в CI (например, пользователь Denozord → префикс denozord).

Шаблон имени и теги

git.shts.su/<owner>/<имя_образа>:<тег>

Теги: latest, короткий SHA коммита (7 символов), sha-<полный_sha> — см. .gitea/README.md.

Платформа образов из CI: linux/amd64 (на другой архитектуре pull пройдёт, но запуск может быть невозможен без своей сборки).

Вход в реестр (если пакеты не публичные)

На сервере или в PowerShell перед docker pull:

docker login git.shts.su

Укажите учётную запись Gitea и PAT / пароль приложения с правом чтения пакетов (или токен, который принимает ваш реестр).

Ссылки и команды docker pull

Ниже пример для владельца denozord — замените сегмент пути на своего владельца репозитория в нижнем регистре. В веб-интерфейсе все контейнерные пакеты можно открыть разом: список пакетов denozord на git.shts.su. Если прямая ссылка на версию latest не открывается (зависит от версии Gitea), откройте общий список пакетов и выберите нужный образ по имени.

Образ	Назначение	Страница пакета (пример)	Pull
evobgp-api	HTTP API (с birdc в образе)	packages/…/evobgp-api	docker pull git.shts.su/denozord/evobgp-api:latest
evobgp-all	Монолит microVPS: API + in-process воркеры scheduler/ingest/render/deploy	packages/…/evobgp-all	docker pull git.shts.su/denozord/evobgp-all:latest
evobgp-scheduler	Планировщик (reference)	packages/…/evobgp-scheduler	docker pull git.shts.su/denozord/evobgp-scheduler:latest
evobgp-ingest	Ingest CDN / ETag	packages/…/evobgp-ingest	docker pull git.shts.su/denozord/evobgp-ingest:latest
evobgp-render	Render	packages/…/evobgp-render	docker pull git.shts.su/denozord/evobgp-render:latest
evobgp-deploy	Deploy	packages/…/evobgp-deploy	docker pull git.shts.su/denozord/evobgp-deploy:latest
evobgp-node	Нода на площадке	packages/…/evobgp-node	docker pull git.shts.su/denozord/evobgp-node:latest
evobgp-web	Статика UI + nginx	packages/…/evobgp-web	docker pull git.shts.su/denozord/evobgp-web:latest
evobgp-agent	Агент (bird2 в образе)	packages/…/evobgp-agent	docker pull git.shts.su/denozord/evobgp-agent:latest
evobgp-bird2	Только BIRD2	packages/…/evobgp-bird2	docker pull git.shts.su/denozord/evobgp-bird2:latest

На Linux-сервере команды docker pull и docker login такие же (выполняйте в обычном shell).

Запуск контейнера с готового образа (минимум)

После pull, например только API (порты и переменные подставьте свои):

docker run --rm -p 8080:8080 `
  -e EVOBGP_DATABASE_URL="postgres://user:pass@host:5432/evobgp?sslmode=disable" `
  -e EVOBGP_HTTP_ADDR=":8080" `
  git.shts.su/denozord/evobgp-api:latest

Для полного стека удобнее Compose из репозитория: по умолчанию он собирает из исходников (--build). Чтобы использовать уже скачанные образы из реестра, задайте в override-файле или правке deploy/compose/docker-compose.yaml у сервисов поле image: вместо build: с тем же префиксом git.shts.su/<owner>/... и тегом (:latest или зафиксированный :sha-... для воспроизводимости). Подробности CI и имён — .gitea/README.md.

Вариант 1: Docker, профиль microvps

Один процесс evobgp-all (HTTP API + in-process воркеры scheduler, ingest, render, deploy), PostgreSQL, BIRD2, evobgp-agent.

cd deploy\compose
docker compose --profile microvps up -d --build

Ожидаемые сервисы:

• API: http://localhost:8080 (внутри контейнера EVOBGP_HTTP_ADDR=:8080).
• BGP: порт 179/tcp проброшен с контейнера BIRD (для отладки; в проде часто нужен network_mode: host или отдельная сеть — см. комментарии в docker-compose.yaml).

Проверка живости (без ключа):

Invoke-RestMethod -Uri "http://localhost:8080/v1/health"

Остановка:

docker compose --profile microvps down

Полная очистка томов (осторожно, удалит данные БД):

docker compose --profile microvps down -v

Вариант 2: Docker, профиль reference

Эталонное разбиение: отдельные контейнеры evobgp-api, evobgp-scheduler, evobgp-ingest, evobgp-render, evobgp-deploy, сервис NATS JetStream (в compose; привязка очереди задач к брокеру — следующая итерация), веб UI за nginx, опционально Prometheus.

cd deploy\compose
docker compose --profile reference up -d --build

Полезные порты:

Порт	Назначение
8080	HTTP API (evobgp-api)
3000	Веб UI (evobgp-web → nginx, прокси на API)
4222	NATS
9090	Prometheus (в compose)
179	BGP (BIRD2)

Воркеры reference: evobgp-scheduler ходит в API по HTTP (EVOBGP_CONTROL_PLANE_URL, EVOBGP_SCHEDULER_BEARER); в docker-compose.yaml для локального запуска включены EVOBGP_DEV_INSECURE=1 на API и токен dev у планировщика. evobgp-ingest обновляет ETag CDN-источников; evobgp-render по умолчанию не трогает published_revision (включите EVOBGP_RENDER_AUTOPUBLISH=1 осознанно); evobgp-deploy пишет в лог расхождение applied vs published. Очередь jobs остаётся in-process у evobgp-api; общий брокер — в планах.

В evobgp-all (microvps) те же пакеты крутятся в одном процессе и используют общий jobs.Registry без HTTP.

Вариант 3: Локально без Docker (только API)

1. Поднимите PostgreSQL и создайте БД (или используйте существующую).
2. Установите переменные окружения в текущей сессии PowerShell:

$env:EVOBGP_DATABASE_URL = "postgres://user:pass@localhost:5432/evobgp?sslmode=disable"
$env:EVOBGP_HTTP_ADDR = ":8080"
# Ключи обязательны для защищённых маршрутов (пример формата см. access.md)
$env:EVOBGP_API_KEYS = "op|YOUR_TENANT_ID|operator"

3. Запуск только HTTP API:

cd <корень-клона-репозитория>
go run .\cmd\evobgp-api

Или монолит microVPS (тот же API плюс горутины тех же воркеров scheduler/ingest/render/deploy):

go run .\cmd\evobgp-all

При старте в лог выводится публичный ключ бандла (base64) — его нужно передать на сторону evobgp-node для проверки подписи. При включённом демо-сиде (EVOBGP_SEED_DEMO не равен 0, поведение по умолчанию) сервер также печатает подсказку с примером EVOBGP_API_KEYS.

Для разработки без настройки ключей (только демо-данные):

$env:EVOBGP_DEV_INSECURE = "1"
go run .\cmd\evobgp-api

Запросы с заголовком Authorization: Bearer dev получают роль operator в демо-tenant. Не включайте в продакшене.

Вариант 4: Веб-интерфейс (разработка)

cd web
npm install
npm run dev

Укажите в окружении API список разрешённых origin для CORS (пример для Vite на порту 5173):

$env:EVOBGP_CORS_ORIGINS = "http://localhost:5173,http://127.0.0.1:5173"

В эталонном Compose для evobgp-api уже заданы origin для 5173 и 3000 — см. deploy/compose/docker-compose.yaml.

Пересборка HTML из OpenAPI

После правок docs/openapi.yaml:

.\scripts\build-openapi-html.ps1

Подробности — OPENAPI-GITEA.md.

Дальше

• access.md — как выдать ключи и настроить ноду.
• architecture.md — состав сервисов и пакетов.