From 793908ae149de8338ab2a8af2b061bc4516a78b5 Mon Sep 17 00:00:00 2001 From: hermes Date: Thu, 27 Aug 2026 11:57:44 +0000 Subject: [PATCH 01/15] docs: add production architecture diagram in three formats - README.md explains what's shown vs not, known TODOs, when to pick which - mermaid.md: Mermaid flowchart, renders inline in Gitea PR preview - standalone.svg: raw SVG, embeddable as image in any README/wiki - standalone.html: HTML wrapper with dark theme + summary cards All three show the same graph: - 2 swarm nodes (odroid manager, xu4 worker) - 7 stacks on odroid: gitea, hermes, hermes_infra, immich, brencher, brencher2, gmail_mcp, torrserv_proxy - external: Keenetic router, Tailscale subnet, Client - dead: nginx_nginx (Replicas=0) - deploy flow: brencher -> stacks Snapshot 2026-08-27, sources: docker_socket_proxy + gitea admin API --- docs/architecture/README.md | 69 +++++++ docs/architecture/mermaid.md | 89 +++++++++ docs/architecture/standalone.html | 304 ++++++++++++++++++++++++++++++ docs/architecture/standalone.svg | 233 +++++++++++++++++++++++ 4 files changed, 695 insertions(+) create mode 100644 docs/architecture/README.md create mode 100644 docs/architecture/mermaid.md create mode 100644 docs/architecture/standalone.html create mode 100644 docs/architecture/standalone.svg diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..6ada173 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,69 @@ +# Production architecture + +Три варианта одной диаграммы продакшна. Выбери удобный и оставь только его (или предложи другой). + +> **Snapshot:** 2026-08-27 +> **Sources:** `docker_socket_proxy` (read-only) + gitea admin API + gitea_server logs +> **Один и тот же граф**, разные форматы. + +## Что показывает + +- 2 swarm nodes: **odroid** (manager, 192.168.1.96) и **xu4** (worker, пуст в снапшоте) +- 7 stacks на odroid: gitea, hermes, hermes_infra, immich, brencher, brencher2, gmail_mcp, torrserv_proxy +- External: Keenetic router (DNS + Let's Encrypt TLS termination), Tailscale (subnet router — транспорт), Client +- Dead component: `nginx_nginx` (jwilder/nginx-proxy, Replicas=0) +- Deploy flow: brencher → стеки + +## Что НЕ показывает (для следующих уровней) + +- Каждый отдельный контейнер и его IP в overlay-сетях +- Volume mounts и где лежат данные (особенно `gitea_data` NFS на 192.168.1.96) +- Swarm secrets (LFS_JWT_SECRET, JWT_SECRET, INTERNAL_TOKEN) +- DNS-резолвинг детально (search `anoa-bebop.ts.net`, ExtServers 192.168.1.1) +- Traffic flow конкретных сервисов (gmail MCP, immich ML pipeline и т.д.) + +## Известные неточности (TODO перед фиксацией) + +1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует — legacy endpoint или ручной `docker service update --publish-add`. +2. `xu4` worker пуст в снапшоте — перепроверить перед merge. +3. `nginx_nginx` Replicas=0 — dead, но overlay-сеть `nginx_ingress` (10.0.3.0/24) жива. +4. Tailscale роль — subnet router (подтверждено), но MagicDNS для `rudolf.keenetic.link` неизвестно. +5. brencher-stack-compose для каждого стека отсутствует в `admin/ansible` (только `poc/*`) — долг. + +## Варианты + +| Файл | Формат | Где рендерится | Плюсы | Минусы | +|---|---|---|---|---| +| `mermaid.md` | Markdown + Mermaid | Gitea UI, PR preview, любой MD-рендерер | Diff-friendly, версионируется, не требует внешних тулзов | Стиль спартанский, нет полного layout-control | +| `standalone.svg` | Raw SVG | Браузер, можно вставить в README/wiki/slack | Single file, no deps, точный layout | Ручная правка, нет динамики | +| `standalone.html` | HTML + inline SVG + dark theme | Браузер | Красиво (pulsing dot, summary cards), single file, no JS | Не рендерится в Gitea preview, нужен браузер | + +## Какой выбрать + +**Если важно версионировать и видеть diff в PR** → `mermaid.md`. Он рендерится прямо в Gitea. + +**Если важно показать всем (внешним людям, в презентации, в slack)** → `standalone.html`. Открывается в браузере, выглядит презентабельно. + +**Если нужен в README.md файле как изображение** → `standalone.svg`. Вставляется как `![arch](docs/architecture/standalone.svg)`. + +## Связанные тикеты + +- `admin/ansible#7` — gitea stack actually deploys (RCA для og:url warning) +- `admin/ansible#5` — re-deploy `hermes_squid` from feat/docker-socket-proxy-readonly +- `admin/ansible#6` — pre-create `socket_proxy` overlay network + +## Следующие уровни (если зайдёт этот стиль) + +- **Level 2 — Network diagram:** все 22 overlay-сети, какие контейнеры в каких, IP-адреса +- **Level 3 — Service topology:** gitea stack целиком (server + runner + volumes + secrets + DB) +- **Level 4 — Deploy flow:** brencher → git pull → docker stack deploy → brencher-state-proxy отчёт +- **Level 5 — Secrets/Vault:** где лежат LFS_JWT_SECRET, JWT_SECRET, gmail token, registry auth + +## Редактирование + +Все три файла можно править руками: +- `mermaid.md` — поменять Mermaid-блок +- `standalone.svg` — поменять ``, ``, `` +- `standalone.html` — поменять CSS или SVG-блок + +После правок пересмотри в браузере. Когда устаканится — коммить в `docs/architecture/` этого репо. diff --git a/docs/architecture/mermaid.md b/docs/architecture/mermaid.md new file mode 100644 index 0000000..3e2aa2b --- /dev/null +++ b/docs/architecture/mermaid.md @@ -0,0 +1,89 @@ +# Production architecture — variant 1: Mermaid + +> **Формат:** Mermaid внутри Markdown. Рендерится прямо в Gitea (preview в PR, page view). +> Diff-friendly, версионируется вместе с кодом, не требует внешних тулзов. + +## Level 1: Cluster overview + +```mermaid +flowchart TB + Client(["Client
из tailscale-сети"]) + + subgraph EXT["External (LAN 192.168.1.0/24)"] + Keenetic["Keenetic router
192.168.1.1
DNS + Let's Encrypt
TLS termination"] + Tailscale["Tailscale
subnet router на odroid
только транспорт"] + end + + subgraph SWARM["Docker Swarm cluster"] + subgraph ODROID["Node: odroid (manager)
192.168.1.96 · arm64 · Linux 5.15"] + direction TB + Ingress["swarm ingress-endpoint
10.0.0.2
(routing mesh)"] + + subgraph STACKS["Stacks"] + direction LR + Gitea["gitea stack
gitea_server (3000)
gitea_runner
gitea_gitea 10.0.17/24"] + Hermes["hermes stack
hermes-agent
hermes-gateway"] + HermesInfra["hermes_infra stack
squid · sarg · hermes-ui
docker_socket_proxy
brencher-state-proxy"] + Immich["immich stack
server · db · redis · ml
10.0.2.0/24"] + Brencher["brencher · brencher2
deploy tools"] + GmailMCP["gmail_mcp
gmail + telegram MCP"] + Torrserv["torrserv_proxy
reverseproxy · fileserver"] + end + + NginxDead["nginx_nginx
jwilder/nginx-proxy
Replicas: 0 (dead)"] + end + + subgraph XU4["Node: xu4 (worker)"] + Worker["worker tasks
(пусто в снапшоте)"] + end + end + + Client -->|"https://gitea.rudolf.keenetic.link
(tailscale subnet)"| Tailscale + Tailscale -->|"HTTPS"| Keenetic + Keenetic -->|"plain HTTP после TLS term"| Ingress + Ingress -->|"swarm routing
(endpoint.Ports stale)"| Gitea + Ingress --> Immich + Ingress --> Hermes + + NginxDead -.->|"сеть есть
контейнеров нет"| Ingress + + Brencher -.->|"deploys"| Gitea + Brencher -.->|"deploys"| Immich + Brencher -.->|"deploys"| HermesInfra + + classDef external fill:#1e293b,stroke:#94a3b8,color:#e2e8f0 + classDef node fill:#0f172a,stroke:#fbbf24,color:#fef3c7 + classDef stack fill:#0c4a6e,stroke:#22d3ee,color:#cffafe + classDef dead fill:#1f1717,stroke:#fb7185,color:#fecaca,stroke-dasharray: 4 4 + classDef edge fill:#064e3b,stroke:#34d399,color:#d1fae5 + + class Client,Keenetic,Tailscale external + class ODROID,XU4 node + class STACKS stack + class Gitea,Hermes,HermesInfra,Immich,Brencher,GmailMCP,Torrserv stack + class NginxDead dead + class Ingress edge +``` + +## Плюсы / минусы + +**+** Рендерится в Gitea сразу, без дополнительных инструментов. +**+** Plain text, mergeable, diff-friendly. +**+** Легко править — текстовый формат. +**+** Gitea поддерживает `classDef`, subgraphs, разные стрелки. +**-** Стиль Mermaid спартанский (не dark theme by default — нужны `classDef`). +**-** Большие графы плохо помещаются в PR preview. +**-** Сложные layout-ы (force-directed) не поддерживаются. + +## Известные неточности в данных + +1. `endpoint.Ports` у gitea_server пустое, но ingress маршрутизирует — legacy endpoint или ручной `service update --publish-add`. +2. `xu4` worker пуст в снапшоте 2026-08-27 — перепроверить перед фиксацией. +3. `nginx_nginx` Replicas=0 — "dead" блок показан отдельно. +4. Tailscale роль: subnet router (транспорт), не MagicDNS — но это требует подтверждения. + +## Связанные файлы + +- `standalone.svg` — тот же граф в raw SVG (вариант 2) +- `standalone.html` — тот же граф в HTML-обёртке (вариант 3) +- `../README.md` — обзор всех вариантов diff --git a/docs/architecture/standalone.html b/docs/architecture/standalone.html new file mode 100644 index 0000000..7d88ea8 --- /dev/null +++ b/docs/architecture/standalone.html @@ -0,0 +1,304 @@ + + + + +Production architecture · Cluster overview + + + +
+
+ +

Production architecture · Cluster overview

+
+
+ Snapshot 2026-08-27 · sources: docker_socket_proxy (read-only) + gitea admin API + gitea_server logs +
+ +
+ + Production architecture · Cluster overview + + + + + + + + + + + + + + + + + + + EXTERNAL (LAN 192.168.1.0/24) + + Client + из tailscale-сети + + Tailscale + subnet router + + Keenetic + DNS + TLS term + 192.168.1.1 + + + + + + + + DOCKER SWARM CLUSTER + + + + Node: odroid (manager) + 192.168.1.96 · arm64 · Linux 5.15 · id=j9bljgaqh9qc + + + + swarm ingress + 10.0.0.2 + (routing mesh) + + + STACKS + + + + + gitea + gitea_server (3000) + gitea_runner + gitea_gitea 10.0.17/24 + ingress: 10.0.0.235 + + + hermes + hermes-agent + hermes-gateway + ingress: 10.0.0.204 + + + hermes_infra + squid · sarg · hermes-ui + docker_socket_proxy + brencher-state-proxy + ingress: 10.0.0.106/108 + + + immich + server · db + redis · ml + 10.0.2.0/24 + .225 / .13 + + + brencher · brencher2 + deploy tools + ingress: 10.0.0.105 + 10.0.0.102 + + + gmail_mcp + gmail-mcp-server + telegram-mcp-server + 10.0.0.6 / 10 + + + torrserv_proxy + reverseproxy + fileserver + .15 / .12 + + + + + nginx_nginx (dead) + jwilder/nginx-proxy · Replicas: 0 + контейнеров нет, overlay-сеть nginx_ingress жива + + + + Node: xu4 (worker) + id=u2ynmimtl0lu + + worker tasks + (пусто в снапшоте 2026-08-27 — перепроверить) + + + + + LEGEND + + external + + node + + stack + + edge / routing + + dead / disabled + + solid = flow + + dashed = deploy + + + + + plain HTTP + post TLS term + + + to gitea + + + + + + + + deploys + + + + + overlay-сеть жива,
контейнеров нет + +
+ + +
+
+

Что показывает

+
    +
  • 2 swarm nodes (odroid manager, xu4 worker)
  • +
  • 7 stacks on odroid (gitea, hermes, hermes_infra, immich, brencher, gmail_mcp, torrserv_proxy)
  • +
  • External: Keenetic router, Tailscale subnet, Client
  • +
  • Dead component: nginx_nginx (Replicas=0)
  • +
  • Deploy flow: brencher → stacks (dashed arrows)
  • +
+
+
+

Чего НЕ показывает

+
    +
  • Каждый отдельный контейнер в overlay-сетях
  • +
  • Volume mounts и где лежат данные
  • +
  • Swarm secrets (LFS_JWT_SECRET, JWT_SECRET)
  • +
  • DNS-резолвинг (search anoa-bebop.ts.net)
  • +
  • Traffic flow отдельных сервисов
  • +
+
+
+

Известные TODO

+
    +
  • endpoint.Ports у gitea_server пустое, но ingress маршрутизирует — legacy
  • +
  • xu4 worker пуст в снапшоте 2026-08-27
  • +
  • nginx_nginx Replicas=0 — dead
  • +
  • Tailscale роль требует подтверждения (subnet vs MagicDNS)
  • +
  • Дополнительные уровни: networks, secrets, deploy flow
  • +
+
+
+ + +
+ + diff --git a/docs/architecture/standalone.svg b/docs/architecture/standalone.svg new file mode 100644 index 0000000..f15fe7b --- /dev/null +++ b/docs/architecture/standalone.svg @@ -0,0 +1,233 @@ + + + Production architecture · Cluster overview (snapshot 2026-08-27) + Dark-themed SVG showing 2 swarm nodes (odroid manager + xu4 worker), 7 stacks on odroid (gitea, hermes, hermes_infra, immich, brencher, gmail_mcp, torrserv_proxy), external entities (Keenetic, Tailscale, Client), and a dead nginx_nginx service with Replicas=0. + + + + + + + + + + + + + + + + + + + + + + + + + + Production architecture · Cluster overview + + + Source: docker_socket_proxy (read-only) + gitea API + gitea_server logs · Snapshot 2026-08-27 + + + + + + + + EXTERNAL (LAN 192.168.1.0/24) + + + + Client + из tailscale-сети + + + + Tailscale + subnet router + + + + Keenetic + DNS + TLS term + 192.168.1.1 + + + + + + tails + + + + + + + DOCKER SWARM CLUSTER + + + + + + Node: odroid (manager) + 192.168.1.96 · arm64 · Linux 5.15 · id=j9bljgaqh9qc + + + + swarm ingress + 10.0.0.2 + (routing mesh) + + + STACKS + + + + gitea + gitea_server (3000) + gitea_runner + gitea_gitea 10.0.17/24 + ingress: 10.0.0.235 + + + + hermes + hermes-agent + hermes-gateway + ingress: 10.0.0.204 + + + + hermes_infra + squid · sarg · hermes-ui + docker_socket_proxy + brencher-state-proxy + + + + immich + server · db + redis · ml + 10.0.2.0/24 + + + + brencher · brencher2 + deploy tools + ingress: 10.0.0.105 + 10.0.0.102 + + + + gmail_mcp + gmail-mcp-server + telegram-mcp-server + 10.0.0.6 / 10 + + + + torrserv_proxy + reverseproxy + fileserver + + + + nginx_nginx (dead) + jwilder/nginx-proxy · Replicas: 0 + контейнеров нет, overlay-сеть nginx_ingress жива + + + + + + Node: xu4 (worker) + id=u2ynmimtl0lu + + + worker tasks + (пусто в снапшоте 2026-08-27 — перепроверить) + + + + + + + + LEGEND + + + external + + + node + + + stack + + + edge / routing + + + dead / disabled + + + solid arrow = flow + + + dashed arrow = deploy + + + + + + + + + plain HTTP + post TLS term + + + + to gitea_server + + + + + + + + + + deploys + + + + deploys + + + + + + + overlay-сеть жива,
контейнеров нет
+ + + + generated 2026-08-27 · sources: docker_socket_proxy + gitea admin API · single file, no external deps + + -- 2.54.0 From 7dab6c89ad055eff6d47b74e839311b48ef619b6 Mon Sep 17 00:00:00 2001 From: hermes Date: Thu, 27 Aug 2026 12:03:50 +0000 Subject: [PATCH 02/15] docs: add svg-embedded variant (markdown referencing standalone.svg) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Test confirmed via /api/v1/markdown that Gitea 1.27 renders ![arch](path.svg) as — SVG displays inline in PR preview and clickable for fullscreen. Variant #4 alongside mermaid / svg / html. User picks one after review. --- docs/architecture/svg-embedded.md | 75 +++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/architecture/svg-embedded.md diff --git a/docs/architecture/svg-embedded.md b/docs/architecture/svg-embedded.md new file mode 100644 index 0000000..634ea5c --- /dev/null +++ b/docs/architecture/svg-embedded.md @@ -0,0 +1,75 @@ +# Production architecture (SVG-embedded variant) + +> Этот файл — **вариант №4**: SVG-картинка, встроенная в Markdown. +> Выбери этот вариант если хочешь чтобы диаграмма была видна прямо в README/PR preview, +> но при этом SVG-файл лежал отдельно и его можно было экспортировать/редактировать независимо. + +## Как это работает + +```markdown +![Production architecture](./standalone.svg) +``` + +Gitea 1.27 (наш self-hosted) рендерит это как `` — SVG отображается +как картинка, можно зумить и качать правой кнопкой. + +## Диаграмма + +![Production architecture](./standalone.svg) + +## Плюсы / минусы этого подхода + +**+** Файл `.md` остаётся читаемым (одна строчка `![alt](path)`). +**+** SVG-файл редактируется отдельно — diff читаемый в обоих файлах. +**+** Работает в любом markdown-рендерере (Gitea, GitHub, GitLab, VS Code preview). +**+** SVG можно переиспользовать в `standalone.html`, в slack, в презентации. +**-** В Gitea preview SVG рендерится как картинка, не inline. Чтобы изменить — нужно править `standalone.svg`. +**-** Размер preview в PR фиксированный (по умолчанию Gitea ресайзит большие SVG до 800px по ширине). + +## Альтернативы (если этот не зайдёт) + +### Inline SVG прямо в .md + +Вместо ссылки можно вставить весь SVG в файл: + +```html +
+Inline SVG (нажми чтобы раскрыть) + + + ...весь SVG здесь... + +
+``` + +**+** Можно зумить, выделять элементы прямо в Gitea UI. +**-** Файл `.md` раздувается до сотен строк SVG-кода. +**-** Diff нечитаемый — каждое изменение в geometry ломает review. +**-** Дублирование: один и тот же SVG в двух местах репо. + +### HTML `` вместо markdown + +```html +Production architecture +``` + +**+** Можно управлять размером (`width`, `height`). +**-** Ничего не даёт по сравнению с markdown-вариантом в Gitea 1.27. + +## Где какой вариант использовать + +| Сценарий | Рекомендация | +|---|---| +| README на главной странице репо | `![arch](path.svg)` — этот файл | +| PR preview в Gitea | `![arch](path.svg)` работает в "Files changed" → preview | +| Wiki-страница | `![arch](path.svg)` | +| Внешний share (email, slack) | `standalone.svg` как attachment | +| Презентация / документ | `standalone.html` (открыть в браузере) | +| PR-описание | `standalone.svg` как attachment в комментарий | + +## Связанные файлы + +- `mermaid.md` — вариант с Mermaid flowchart +- `standalone.svg` — собственно SVG-файл, на который ссылается этот .md +- `standalone.html` — HTML-обёртка с inline SVG и summary cards +- `README.md` — обзор всех вариантов -- 2.54.0 From e8fa7e8be4653497aeccab54dfb8c74a32dce159 Mon Sep 17 00:00:00 2001 From: hermes Date: Thu, 27 Aug 2026 12:08:33 +0000 Subject: [PATCH 03/15] docs: add svg-sized, svg-inline, svg-object variants MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three more ways to embed standalone.svg in markdown: - svg-sized.md: with explicit width="1200" (sanitized style attr doesn't pass) - svg-inline.md: full SVG inline in
— zoomable in preview but diff-unfriendly - svg-object.md: — TESTED via /api/v1/markdown, gitea 1.27 sanitizes it out. Kept for comparison; doesn't work in our gitea UI. --- docs/architecture/svg-inline.md | 119 ++++++++++++++++++++++++++++++++ docs/architecture/svg-object.md | 45 ++++++++++++ docs/architecture/svg-sized.md | 47 +++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 docs/architecture/svg-inline.md create mode 100644 docs/architecture/svg-object.md create mode 100644 docs/architecture/svg-sized.md diff --git a/docs/architecture/svg-inline.md b/docs/architecture/svg-inline.md new file mode 100644 index 0000000..a839b97 --- /dev/null +++ b/docs/architecture/svg-inline.md @@ -0,0 +1,119 @@ +# Production architecture (inline SVG variant) + +> **Вариант №6:** SVG **целиком inline** в markdown, обёрнут в `
` чтобы md-файл +> остался читаемым. Раскрываешь — видишь интерактивный SVG с возможностью зума. + +## Зачем + +- SVG можно зумить в браузере (Ctrl+Scroll) +- Можно выделять элементы, copy-paste текст +- Нет зависимости от внешнего файла + +
+📊 Click to expand inline SVG (snapshot 2026-08-27) + + + Production architecture (compact) + + + + + EXTERNAL + + Client + + Tailscale + + Keenetic + + + + DOCKER SWARM CLUSTER + + + + odroid (manager) · 192.168.1.96 + + + + swarm ingress + 10.0.0.2 + + + + + + + + + + + + + gitea + server · runner + .235 / .17.13 + hermes + agent · gateway + .204 + hermes_infra + squid · sarg + docker_proxy + brencher-state + immich + server · db + redis · ml + brencher + .105 / .102 + deploys ↓ + gmail_mcp + gmail · tg + .6 / .10 + torrserv + proxy · fs + .15 / .12 + + + + + nginx_nginx (dead) · Replicas: 0 + jwilder/nginx-proxy · overlay-сеть nginx_ingress жива + контейнеров нет + + + + xu4 (worker) + + worker tasks + (пусто в снапшоте 2026-08-27) + + + + + + + + + + + + + compact inline variant · same data as standalone.svg + + +
+ +## Плюсы / минусы + +**+** Можно зумить, выделять элементы прямо в Gitea preview. +**+** Нет зависимости от внешнего файла (один .md — всё в нём). +**+** Спасает если SVG-файл случайно удалят. +**-** `.md` файл становится в ~2 раза длиннее. +**-** Diff нечитаемый — каждое изменение в geometry SVG ломает review. +**-** Дублирование данных: один и тот же граф в standalone.svg И в этом .md. + +## Когда использовать + +- Хочешь чтобы диаграмма точно была видна даже если файл `standalone.svg` случайно удалят +- Превью в PR preview без загрузки внешних ресурсов +- Когда диаграмма маленькая и diff читаемый diff --git a/docs/architecture/svg-object.md b/docs/architecture/svg-object.md new file mode 100644 index 0000000..bd49873 --- /dev/null +++ b/docs/architecture/svg-object.md @@ -0,0 +1,45 @@ +# Production architecture (`` variant) + +> **Вариант №7:** использует `` вместо ``. +> Семантически отличается — `` это embeded content, не изображение. + +## Что это даёт по сравнению с `` + +| Свойство | `` | `` | +|---|---|---| +| В Gitea preview | рендерится как image | **вырезается** санитайзером (проверено через `/api/v1/markdown`) | +| Можно зумить в браузере | да | да | +| Загружает CSS внутри SVG | да | да | +| Загружает `