From c6687b2c91775cef2d51512898064ee521586f92 Mon Sep 17 00:00:00 2001 From: Denozordec Date: Sun, 5 Apr 2026 18:20:18 +0700 Subject: [PATCH] docs: enhance README and CI workflow to clarify Docker image build conditions and Gitea Container Registry usage, including new job flags for OpenAPI and code changes --- .gitea/README.md | 13 ++++- .gitea/workflows/ci.yaml | 72 ++++++++++++++++++++------- deploy/docker/bird2/Dockerfile | 2 +- deploy/docker/evobgp-agent/Dockerfile | 5 +- deploy/docker/evobgp-web/Dockerfile | 5 +- deploy/docker/gobinary/Dockerfile | 5 +- docs/README.md | 2 +- docs/overview.md | 1 + docs/quickstart.md | 56 +++++++++++++++++++++ 9 files changed, 134 insertions(+), 27 deletions(-) diff --git a/.gitea/README.md b/.gitea/README.md index d9ece9f..527d6be 100644 --- a/.gitea/README.md +++ b/.gitea/README.md @@ -2,7 +2,16 @@ В репозитории включён workflow [workflows/ci.yaml](workflows/ci.yaml). -Job **openapi** (Redocly) запускается только если в коммите или PR изменились `docs/openapi.yaml` или `redocly.yaml`; иначе шаг пропускается. Остальные jobs (`go`, `bird2`) выполняются как раньше. +Job **changes** вычисляет два флага: + +- **`openapi`** — в диффе есть `docs/openapi.yaml` или `redocly.yaml` → запускается **openapi** (Redocly lint). +- **`code`** — в диффе есть **хотя бы один файл вне «только документация»** → запускаются **go**, **bird2** и при push в main/master **docker-images**. + +Если изменены **только** файлы из списка ниже, **`code=false`**: Go-тесты, bird2 и сборка образов **не** запускаются; при необходимости всё ещё выполняется **openapi**, если трогали OpenAPI или `redocly.yaml`. + +**Список путей «только документация» (без полной сборки):** всё под `docs/`, корневой `README.md`, `web/README.md`, `.gitea/README.md`, `redocly.yaml`. + +Любой другой путь (в т.ч. `.gitea/workflows/ci.yaml`, `go.mod`, `web/package.json`, `deploy/**`, `**/*.go`) включает полный пайплайн. Требования к runner: @@ -56,6 +65,8 @@ git.shts.su//<имя>:<тег> docker pull git.shts.su/myuser/evobgp-api:latest ``` +Полная таблица образов, тегов, ссылок на страницы пакетов в Gitea и минимальный `docker run` для сервера без сборки — в [docs/quickstart.md](../docs/quickstart.md) (раздел «Готовые образы без сборки»). + Убедитесь, что в **Gitea** включены пакеты (Container Registry) и у токена есть права на создание/обновление образов. Другой хост реестра — правьте **`registry:`** и префикс **`IMG=`** в [ci.yaml](workflows/ci.yaml). ### Примечания diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 84eece9..d131ef7 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -10,43 +10,77 @@ jobs: changes: runs-on: ubuntu-latest outputs: - openapi: ${{ steps.openapi.outputs.changed }} + openapi: ${{ steps.detect.outputs.openapi }} + code: ${{ steps.detect.outputs.code }} steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - - id: openapi - name: Detect OpenAPI-related file changes + - id: detect + name: Detect changed paths (OpenAPI vs doc-only vs code) run: | set -euo pipefail - PATHS="docs/openapi.yaml redocly.yaml" - changed=false + + openapi=false + code=true if [ "${{ github.event_name }}" = "pull_request" ]; then base="${{ github.event.pull_request.base.sha }}" head="${{ github.event.pull_request.head.sha }}" - if git diff --name-only "$base" "$head" -- $PATHS | grep -q .; then - changed=true - fi + FILES="$(git diff --name-only "$base" "$head")" else before="${{ github.event.before }}" after="${{ github.sha }}" if [ -n "$before" ] && [ "$before" != "0000000000000000000000000000000000000000" ]; then - if git diff --name-only "$before" "$after" -- $PATHS | grep -q .; then - changed=true - fi + FILES="$(git diff --name-only "$before" "$after")" elif git rev-parse --verify HEAD~1 >/dev/null 2>&1; then - if git diff --name-only HEAD~1 HEAD -- $PATHS | grep -q .; then - changed=true - fi + FILES="$(git diff --name-only HEAD~1 HEAD)" else - # Нет родителя (первый коммит / тонкий clone) — линт OpenAPI выполняем один раз - changed=true + # Нет родителя (первый коммит / тонкий clone) — полный пайплайн + OpenAPI + openapi=true + code=true + echo "openapi=$openapi" >> "$GITHUB_OUTPUT" + echo "code=$code" >> "$GITHUB_OUTPUT" + echo "No parent commit: openapi=true code=true" + exit 0 fi fi - echo "changed=$changed" >> "$GITHUB_OUTPUT" - echo "OpenAPI lint will run: $changed" + # Пустой diff (редко) — не отключаем сборку из осторожности + if [ -z "$(printf '%s' "$FILES" | tr -d '[:space:]')" ]; then + openapi=false + code=true + echo "openapi=$openapi" >> "$GITHUB_OUTPUT" + echo "code=$code" >> "$GITHUB_OUTPUT" + echo "Empty diff: openapi=false code=true" + exit 0 + fi + + if printf '%s\n' "$FILES" | grep -qE '^docs/openapi\.yaml$|^redocly\.yaml$'; then + openapi=true + fi + + doc_only_all=true + while IFS= read -r f || [ -n "${f:-}" ]; do + [ -z "${f:-}" ] && continue + if [[ "$f" == "README.md" || "$f" == ".gitea/README.md" || "$f" == "web/README.md" || "$f" == "redocly.yaml" || "$f" == docs/* ]]; then + continue + fi + doc_only_all=false + break + done <<< "$FILES" + + if $doc_only_all; then + code=false + else + code=true + fi + + echo "openapi=$openapi" >> "$GITHUB_OUTPUT" + echo "code=$code" >> "$GITHUB_OUTPUT" + echo "Changed files (first 20):" + printf '%s\n' "$FILES" | head -n 20 + echo "openapi=$openapi code=$code" openapi: needs: [changes] @@ -61,6 +95,8 @@ jobs: run: npx --yes @redocly/cli@1 lint docs/openapi.yaml go: + needs: [changes] + if: needs.changes.outputs.code == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/deploy/docker/bird2/Dockerfile b/deploy/docker/bird2/Dockerfile index bdf7895..3684a01 100644 --- a/deploy/docker/bird2/Dockerfile +++ b/deploy/docker/bird2/Dockerfile @@ -1,5 +1,5 @@ # BIRD 2 alongside evobgp-agent; share /etc/bird with the agent container (plan §4.1). -FROM debian:bookworm-slim +FROM public.ecr.aws/docker/library/debian:bookworm-slim RUN apt-get update && apt-get install -y --no-install-recommends bird2 \ && rm -rf /var/lib/apt/lists/* COPY deploy/bird/bird.conf /etc/bird/bird.conf diff --git a/deploy/docker/evobgp-agent/Dockerfile b/deploy/docker/evobgp-agent/Dockerfile index d698b15..2875af8 100644 --- a/deploy/docker/evobgp-agent/Dockerfile +++ b/deploy/docker/evobgp-agent/Dockerfile @@ -1,11 +1,12 @@ # evobgp-agent CLI (parse-check, birdc configure); install bird2 so `bird -p` matches bird2 image (plan §13). -FROM golang:1.22-bookworm AS build +# См. gobinary/Dockerfile — ECR Public вместо прямого pull с Docker Hub (устойчивость CI). +FROM public.ecr.aws/docker/library/golang:1.22-bookworm AS build WORKDIR /src COPY go.mod go.sum ./ COPY . . RUN go build -trimpath -ldflags="-s -w" -o /out/evobgp-agent ./cmd/evobgp-agent -FROM debian:bookworm-slim +FROM public.ecr.aws/docker/library/debian:bookworm-slim RUN apt-get update && apt-get install -y --no-install-recommends bird2 ca-certificates \ && rm -rf /var/lib/apt/lists/* COPY --from=build /out/evobgp-agent /usr/local/bin/evobgp-agent diff --git a/deploy/docker/evobgp-web/Dockerfile b/deploy/docker/evobgp-web/Dockerfile index b4fab16..e525cdf 100644 --- a/deploy/docker/evobgp-web/Dockerfile +++ b/deploy/docker/evobgp-web/Dockerfile @@ -1,11 +1,12 @@ # Статическая панель EvoBGP (SvelteKit) + nginx как reverse-proxy к evobgp-api (/v1, /metrics). -FROM node:22-alpine AS build +# ECR Public — то же содержимое, что library/node и library/nginx на Docker Hub. +FROM public.ecr.aws/docker/library/node:22-alpine AS build WORKDIR /web COPY web/package.json web/package-lock.json ./ RUN npm ci COPY web/ ./ RUN npm run build -FROM nginx:1.27-alpine +FROM public.ecr.aws/docker/library/nginx:1.27-alpine COPY deploy/docker/evobgp-web/nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /web/build /usr/share/nginx/html diff --git a/deploy/docker/gobinary/Dockerfile b/deploy/docker/gobinary/Dockerfile index b0bf54e..a35c41a 100644 --- a/deploy/docker/gobinary/Dockerfile +++ b/deploy/docker/gobinary/Dockerfile @@ -1,6 +1,7 @@ # Универсальная сборка бинаря из cmd/* (ARG BIN=evobgp-api | evobgp-all). # INSTALL_BIRDC=1 ставит bird2 в рантайм-образ для EVOBGP_BIRDC_SOCKET (poll метрик birdc). -FROM golang:1.22-bookworm AS build +# Базовые образы из ECR Public (официальное зеркало library/*), чтобы CI не зависел от auth.docker.io. +FROM public.ecr.aws/docker/library/golang:1.22-bookworm AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download @@ -8,7 +9,7 @@ COPY . . ARG BIN=evobgp-api RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/evobgp ./cmd/${BIN} -FROM debian:bookworm-slim +FROM public.ecr.aws/docker/library/debian:bookworm-slim ARG INSTALL_BIRDC=0 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \ && if [ "$INSTALL_BIRDC" = "1" ]; then apt-get install -y --no-install-recommends bird2; fi \ diff --git a/docs/README.md b/docs/README.md index bccd0e2..5015409 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ | Раздел | Описание | |--------|----------| | [overview.md](overview.md) | Ключевые возможности системы | -| [quickstart.md](quickstart.md) | Быстрый запуск: Docker, локальный Go, веб | +| [quickstart.md](quickstart.md) | Быстрый запуск: готовые образы из `git.shts.su`, Docker Compose, локальный Go, веб | | [architecture.md](architecture.md) | Компоненты, потоки данных, пакеты | | [api.md](api.md) | REST: префикс `/v1`, публичные маршруты, ссылки на OpenAPI | | [access.md](access.md) | Выдача доступа: API-ключи, роли, нода, CORS | diff --git a/docs/overview.md b/docs/overview.md index d2be374..ad5ae2e 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -65,6 +65,7 @@ CLI `evobgp-node` поддерживает `pull-bundle`, `verify-bundle`, `appl ## Связанные документы +- [quickstart.md](quickstart.md) — Docker Compose, **готовые образы из Container Registry** (`docker pull git.shts.su/...`) без сборки на сервере. - [api.md](api.md) — как вызывать API на практике. - [architecture.md](architecture.md) — из каких процессов и пакетов это собрано. - [evobgp-api-sketches.md](evobgp-api-sketches.md) — ранние таблицы эндпоинтов (черновик). diff --git a/docs/quickstart.md b/docs/quickstart.md index b93a798..ac67a4c 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -9,6 +9,62 @@ - **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`). + +### Шаблон имени и теги + +```text +git.shts.su//<имя_образа>:<тег> +``` + +**Теги:** `latest`, короткий SHA коммита (7 символов), `sha-<полный_sha>` — см. [.gitea/README.md](../.gitea/README.md). + +**Платформа образов из CI:** `linux/amd64` (на другой архитектуре pull пройдёт, но запуск может быть невозможен без своей сборки). + +### Вход в реестр (если пакеты не публичные) + +На сервере или в PowerShell перед `docker pull`: + +```powershell +docker login git.shts.su +``` + +Укажите учётную запись Gitea и **PAT / пароль приложения** с правом чтения пакетов (или токен, который принимает ваш реестр). + +### Ссылки и команды `docker pull` + +Ниже пример для владельца **`denozord`** — замените сегмент пути на своего владельца репозитория в нижнем регистре. В веб-интерфейсе все контейнерные пакеты можно открыть разом: [список пакетов `denozord` на git.shts.su](https://git.shts.su/denozord/-/packages). Если прямая ссылка на версию `latest` не открывается (зависит от версии Gitea), откройте общий список пакетов и выберите нужный образ по имени. + +| Образ | Назначение | Страница пакета (пример) | Pull | +|--------|------------|--------------------------|------| +| `evobgp-api` | HTTP API (с `birdc` в образе) | [packages/…/evobgp-api](https://git.shts.su/denozord/-/packages/container/evobgp-api/latest) | `docker pull git.shts.su/denozord/evobgp-api:latest` | +| `evobgp-all` | Монолит microVPS: API + заглушки воркеров в одном процессе | [packages/…/evobgp-all](https://git.shts.su/denozord/-/packages/container/evobgp-all/latest) | `docker pull git.shts.su/denozord/evobgp-all:latest` | +| `evobgp-scheduler` | Планировщик (reference) | [packages/…/evobgp-scheduler](https://git.shts.su/denozord/-/packages/container/evobgp-scheduler/latest) | `docker pull git.shts.su/denozord/evobgp-scheduler:latest` | +| `evobgp-ingest` | Ingest CDN / ETag | [packages/…/evobgp-ingest](https://git.shts.su/denozord/-/packages/container/evobgp-ingest/latest) | `docker pull git.shts.su/denozord/evobgp-ingest:latest` | +| `evobgp-render` | Render | [packages/…/evobgp-render](https://git.shts.su/denozord/-/packages/container/evobgp-render/latest) | `docker pull git.shts.su/denozord/evobgp-render:latest` | +| `evobgp-deploy` | Deploy | [packages/…/evobgp-deploy](https://git.shts.su/denozord/-/packages/container/evobgp-deploy/latest) | `docker pull git.shts.su/denozord/evobgp-deploy:latest` | +| `evobgp-node` | Нода на площадке | [packages/…/evobgp-node](https://git.shts.su/denozord/-/packages/container/evobgp-node/latest) | `docker pull git.shts.su/denozord/evobgp-node:latest` | +| `evobgp-web` | Статика UI + nginx | [packages/…/evobgp-web](https://git.shts.su/denozord/-/packages/container/evobgp-web/latest) | `docker pull git.shts.su/denozord/evobgp-web:latest` | +| `evobgp-agent` | Агент (bird2 в образе) | [packages/…/evobgp-agent](https://git.shts.su/denozord/-/packages/container/evobgp-agent/latest) | `docker pull git.shts.su/denozord/evobgp-agent:latest` | +| `evobgp-bird2` | Только BIRD2 | [packages/…/evobgp-bird2](https://git.shts.su/denozord/-/packages/container/evobgp-bird2/latest) | `docker pull git.shts.su/denozord/evobgp-bird2:latest` | + +На **Linux-сервере** команды `docker pull` и `docker login` такие же (выполняйте в обычном shell). + +### Запуск контейнера с готового образа (минимум) + +После pull, например только API (порты и переменные подставьте свои): + +```powershell +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//...` и тегом (`:latest` или зафиксированный `:sha-...` для воспроизводимости). Подробности CI и имён — [.gitea/README.md](../.gitea/README.md). + ## Вариант 1: Docker, профиль microvps Один процесс `evobgp-all` (HTTP API + in-process заглушки воркеров), PostgreSQL, BIRD2, `evobgp-agent`.