diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..887c81d --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,37 @@ +# Architecture diagram + +![Architecture diagram](./standalone-adaptive.svg) + +Snapshot: 2026-08-27. Light/dark theme via `prefers-color-scheme`. + +## What + +- **Left column:** external (Client, Tailscale, Keenetic) + lan + all 22 overlay networks. One block = one network. +- **Right column:** all stacks. Inside each stack — its nodes (containers). + +## How to update + +1. Re-fetch live state from the cluster: + ``` + curl http://docker_socket_proxy:2375/networks | python3 -m json.tool > /tmp/nets.json + curl http://docker_socket_proxy:2375/services | python3 -m json.tool > /tmp/services.json + curl http://docker_socket_proxy:2375/tasks?filters='{"desired-state":"running"}' > /tmp/tasks.json + ``` +2. Compare counts/labels against `standalone-adaptive.svg`. Update blocks that changed. +3. For new stacks/services: add a stack rect in the right column + 1+ node rects inside. +4. For new networks: add a network block in the left column at the matching height. + +Convention: +- `class="net-fill"` — overlay network (amber border) +- `class="net-external-fill"` — Keenetic/lan (slate) +- `class="ext-client-fill"` — Client (violet border) +- `class="stack-fill"` — running stack (cyan border) +- `class="node-fill"` — running container +- `class="node-dead"` — dead/disabled (red dashed) +- IPs in node title reflect current state — refresh when IPs change + +## Sources + +- `docker_socket_proxy` (read-only): `/networks`, `/services`, `/tasks`, `/containers/{id}/json` +- `admin/ansible` repo: `poc/*/stack-compose.yml` for stack definitions +- Gitea admin API: `POST /api/v1/repos/admin/ansible/issues` for tickets about drift diff --git a/docs/architecture/mermaid.md b/docs/architecture/mermaid.md new file mode 100644 index 0000000..a1cbab8 --- /dev/null +++ b/docs/architecture/mermaid.md @@ -0,0 +1,253 @@ +# Architecture diagram — full prod map + +> **Snapshot:** 2026-08-27 · sources: `docker_socket_proxy` + gitea admin API +> +> **Two views:** +> - This file — **Mermaid flow** (high-level topology, all elements) +> - `standalone-adaptive.svg` — **per-node detail** (IPs, container names) + +```mermaid +flowchart LR + %% ==================== EXTERNAL ==================== + subgraph EXT[" "] + direction TB + Client["Client
tailscale"]:::client + Keenetic["Keenetic
DNS · TLS"]:::external + Tailscale["Tailscale
subnet router"]:::external + lan["lan
192.168.1.0/24"]:::external + + Client -->|https| Tailscale + Tailscale --> Keenetic + Keenetic -->|TLS term| lan + end + + %% ==================== INGRESS / EGRESS ==================== + subgraph IO[" "] + direction TB + ingress["ingress
10.0.0.0/24"]:::egress + proxy_egress["squid_egress
hermes_proxy
admin"]:::egress + nginx_nets["nginx_ingress
nginx_default
(DEAD)"]:::egress + + lan -.->|egress| ingress + end + + %% ==================== STACKS (deployed via brencher) ==================== + subgraph BRENCHER_DEPLOYED["via brencher (PROFILES env)"] + direction TB + b_gitea["gitea"]:::stack + b_hermes["hermes"]:::stack + b_hermes_infra["hermes_infra"]:::stack + b_immich["immich"]:::stack + b_gmail_mcp["gmail_mcp"]:::stack + b_torrserv["torrserv_proxy"]:::stack + b_brencher2["brencher2
(deploy tool)"]:::deploy + end + + ingress --> b_gitea + ingress --> b_hermes + ingress --> b_hermes_infra + ingress --> b_immich + ingress --> b_gmail_mcp + ingress --> b_torrserv + + proxy_egress -.-> b_hermes_infra + + b_brencher2 -.->|deploys| b_gitea + b_brencher2 -.->|deploys| b_hermes + b_brencher2 -.->|deploys| b_immich + b_brencher2 -.->|deploys| b_hermes_infra + b_brencher2 -.->|deploys| b_gmail_mcp + b_brencher2 -.->|deploys| b_torrserv + + %% ==================== STACKS (standalone, not via brencher) ==================== + subgraph STANDALONE["standalone (compose или ручной deploy)"] + direction TB + s_dsp["docker_socket_proxy"]:::stack + s_lampa["lampa-jackett
(compose)"]:::stack + s_photosHelper["photosHelper
(DEAD · Replicas: 0)"]:::dead + s_nginx["nginx
(DEAD · Replicas: 0)"]:::dead + s_registry["registry
(DEAD · Replicas: 0)"]:::dead + end + + ingress --> s_dsp + ingress --> s_lampa + + %% ==================== ZOMBIE STACKS (volumes only, no services) ==================== + subgraph ZOMBIE["zombie stacks (volumes orphaned)"] + direction TB + z_nextcloud["nextcloud
(4 volumes)"]:::dead + z_portainer["portainer
(1 volume)"]:::dead + z_swarmpit["swarmpit
(1 volume)"]:::dead + z_sstp["sstp · softether
(4 volumes)"]:::dead + z_test["test
(1 volume)"]:::dead + z_torr_cache["torr_cache
(1 volume)"]:::dead + z_beszel["beszel-poc
(2 volumes)"]:::dead + end + + %% ==================== EPHEMERAL (gitea act_runner jobs) ==================== + subgraph EPHEMERAL["gitea act_runner ephemeral jobs"] + direction TB + eph_jobs["~48 exited
ephemeral job pods
(random names)"]:::ephemeral + end + + b_gitea -.->|spawns| eph_jobs + + %% ==================== INTERNAL NETS (one per stack) ==================== + subgraph INTERNAL["internal nets (12)"] + direction TB + gitea_net["gitea_gitea"]:::internal + hermes_net["hermes_hermes"]:::internal + hi_net["hermes_infra_default"]:::internal + immich_net["immich_default"]:::internal + gmail_net["gmail_mcp_default"]:::internal + torr_net["torrserv_proxy_default"]:::internal + brencher2_nets["brencher2-net +
brencher2_default"]:::internal + dsp_net["dsp_default"]:::internal + lampa_net["lampa_default"]:::internal + + b_gitea --> gitea_net + b_hermes --> hermes_net + b_hermes_infra --> hi_net + b_immich --> immich_net + b_gmail_mcp --> gmail_net + b_torrserv --> torr_net + b_brencher2 --> brencher2_nets + s_dsp --> dsp_net + s_lampa --> lampa_net + end + + %% ==================== VOLUMES (153 total) ==================== + subgraph VOLS["volumes (153 total, 18 mounted · 135 orphaned)"] + direction TB + vol_active["active: gitea_data · immich_* ·
hermes_*_data · brencher_tmp ·
docker_socket_proxy_*_data ·
torrserv_proxy_data · lampa_*"]:::volumes + vol_orphaned["orphaned: 119 (no stack) ·
nextcloud · portainer · sstp ·
swarmpit · test · torr_cache ·
beszel-poc · immich_postgres"]:::dead + end + + %% ==================== SECRETS / CONFIGS (403 from socket proxy) ==================== + subgraph SECRETS["secrets & configs (read-only proxy: 403)"] + direction TB + sec_known["known to exist in gitea app.ini:
LFS_JWT_SECRET · JWT_SECRET ·
SECRET_KEY · INTERNAL_TOKEN"]:::secret + sec_hermes["hermes-agent runtime secrets
(gmail creds · telegram token)"]:::secret + end + + %% ==================== STYLING ==================== + classDef client fill:#0f172a,stroke:#a78bfa,color:#ddd6fe + classDef external fill:#1e293b,stroke:#94a3b8,color:#cbd5e1 + classDef egress fill:#052e16,stroke:#22c55e,color:#bbf7d0 + classDef stack fill:#0c4a6e,stroke:#22d3ee,color:#cffafe + classDef dead fill:#1f1717,stroke:#fb7185,color:#fecaca,stroke-dasharray: 4 2 + classDef deploy fill:#422006,stroke:#fbbf24,color:#fde68a + classDef ephemeral fill:#1e1b4b,stroke:#818cf8,color:#c7d2fe,stroke-dasharray: 2 2 + classDef internal fill:#1e1b4b,stroke:#818cf8,color:#c7d2fe + classDef volumes fill:#0f172a,stroke:#475569,color:#cbd5e1 + classDef secret fill:#0f172a,stroke:#f59e0b,color:#fde68a,stroke-dasharray: 3 2 +``` + +## Полная картина прода + +### 🟢 Running stacks (12) + +**Через `brencher` (PROFILES env):** +1. **gitea** — gitea_server + gitea_runner (act_runner для CI) +2. **hermes** — hermes-agent + hermes-gateway +3. **hermes_infra** — squid + sarg + hermes-ui + hermes-gateway + docker_socket_proxy + brencher-state-proxy +4. **immich** — server + database + redis + machine-learning +5. **gmail_mcp** — gmail-mcp-server + telegram-mcp-server +6. **torrserv_proxy** — reverseproxy + fileserver +7. **brencher2** — второй deploy tool (сам себя не деплоит) + +**Standalone (не через brencher):** +8. **docker_socket_proxy** — standalone, для hermes-gateway +9. **lampa-jackett** — docker-compose, port 9117 + +**DEAD services (но стек определён):** +10. **photosHelper** (Replicas: 0, 1 volume) +11. **nginx** (Replicas: 0, 2 services, 5 volumes) +12. **registry** (Replicas: 0, 1 volume) + +### 🟡 Zombie stacks (volumes, но 0 running services) + +Volumes остались после того как сервисы удалили. 4–5 volumes на стек: + +- **nextcloud** (4 volumes · config + данные) +- **sstp** (4 volumes · SoftEther VPN, конфиг + logs) +- **portainer** (1 volume · swarm UI) +- **swarmpit** (1 volume · swarm UI) +- **test** (1 volume) +- **torr_cache** (1 volume) +- **beszel-poc** (2 volumes · monitoring POC) + +### 🟣 Ephemeral: gitea act_runner job pods + +Когда CI job запускается в gitea, `act_runner` создаёт **ephemeral контейнер** со случайным именем (`romantic_wozniak`, `compassionate_goodall` и т.п.). После завершения контейнер остаётся в `exited` state. На текущий момент ~48 таких exited контейнеров. + +Реестр: image `ghcr.io/immich-app/runner-images:ubuntu-latest` (определён в `poc/gitea/config.yaml`). + +### 🔴 Volumes (153 total) + +- **18 mounted** в running контейнеры +- **135 orphaned** (либо от zombie-стеков, либо anonymous) + +Основные используемые: +- `gitea_data` — критичные данные gitea (NFS на 192.168.1.96:/root/volumes/gitea) +- `immich_*` — uploads, model-cache, postgres +- `hermes_infra_*_data`, `hermes_hermes_*_data` +- `brencher_tmp`, `brencher2_tmp` — git clones +- `lampa_jackett_config` +- `torrserv_proxy_data` + +### 🔐 Secrets & configs + +`/configs` и `/secrets` через socket-proxy **403** (требуется POST:1). Известные по другим источникам: + +**В gitea `/data/gitea/conf/app.ini`:** +- `LFS_JWT_SECRET` +- `JWT_SECRET` (oauth2) +- `SECRET_KEY` +- `INTERNAL_TOKEN` + +**В hermes-agent runtime:** +- Gmail API creds (для gmail_mcp server) +- Telegram bot token (для telegram_mcp server) + +**Swarm configs** (из `poc/gitea/stack-compose.yml`): +- `runner_config` — `config.yaml` для act_runner + +### 🗑️ Dead-overlay сети (сеть есть, контейнеров нет) + +- `nginx_ingress` (10.0.3.0/24) — для nginx-proxy, но nginx Replicas=0 +- `nginx_default` (10.0.4.0/24) — то же + +Сети **живые** в swarm mesh, но не используются. + +## Что НЕ показывает эта диаграмма + +- Конкретные IP контейнеров (см. `standalone-adaptive.svg`) +- Cross-stack сети в деталях (см. SVG) +- Точные timestamps exited containers +- Полный список 119 orphaned volumes без stack'а + +## Как обновить + +Запусти в этом окружении: + +```bash +# Stacks & services +curl http://docker_socket_proxy:2375/services | jq -r '.[] | .Spec.Labels["com.docker.stack.namespace"]' | sort -u + +# Volumes per stack +curl http://docker_socket_proxy:2375/volumes | jq -r '.Volumes[] | "\(.Name) \(.Labels["com.docker.stack_namespace"] // "no-stack")"' + +# Ephemeral containers (exited) +curl http://docker_socket_proxy:2375/containers/json?all=1 | jq '[.[] | select(.State=="exited")] | length' + +# BRENCHER profiles (env var) +curl http://docker_socket_proxy:2375/containers/brencher_brencher-backend* 2>/dev/null +``` + +## Связанные + +- `standalone-adaptive.svg` — per-node detail (IPs, container names) +- `admin/ansible#5` — re-deploy hermes_squid +- `admin/ansible#6` — pre-create socket_proxy overlay +- `admin/ansible#7` — gitea stack deploy / app.ini fix diff --git a/docs/architecture/standalone-adaptive.svg b/docs/architecture/standalone-adaptive.svg new file mode 100644 index 0000000..e68f64b --- /dev/null +++ b/docs/architecture/standalone-adaptive.svg @@ -0,0 +1,487 @@ + + + Production architecture · internet / ingress-egress / stacks / internal-nets + + 4 columns: + 1. Internet (Client, Tailscale, Keenetic, lan) + 2. Ingress & egress networks (10) + 3. Stacks with nodes (12 stacks) + 4. Internal-only networks (12, paired with their stack's y) + + + + + + + + + + + + + + + + + + + + + + + + Production architecture · 4 columns + + + + 1. INTERNET + + + + Client + из tailscale-сети + 100.x.x.x + + + + + Keenetic router + 192.168.1.1 · DNS · TLS term + .rudolf.keenetic.link → 192.168.1.96:443 + Tailscale subnet + announces 192.168.1.0/24 + + + + + lan + 192.168.1.0/24 · физическая LAN + + + + 2. INGRESS / EGRESS + могут выйти в интернет + + + ingress + 10.0.0.0/24 + swarm routing mesh + + + + nginx_ingress + 10.0.3.0/24 + nginx-proxy · dead + + + + nginx_default + 10.0.4.0/24 + nginx-proxy · dead + + + + hermes_infra_squid_egress + 10.0.12.0/24 + squid + + + + hermes_infra_admin + 10.0.14.0/24 + admin overlay + + + + hermes_infra_hermes_proxy + 10.0.15.0/24 + hermes + + + + docker_socket_proxy_socket_proxy + 10.0.16.0/24 + docker socket + + + + docker_socket_proxy_admin + 10.0.18.0/24 + admin overlay + + + + docker_socket_proxy_hermes_proxy + 10.0.19.0/24 + hermes + + + + docker_socket_proxy_squid_egress + 10.0.20.0/24 + squid + + +STACKS & PODS + +gitea + +gitea_server.1.fx8lrhxza6s7xhjeqr46oiioa +10.0.0.235 ingress · 10.0.17.13 gitea_gitea · 10.0.3.134 nginx_ingress + + +gitea_runner.1.7qu01adpg71cpk5seaa22ve76 +10.0.0.6 ingress · gitea_gitea + + + +hermes + +hermes_hermes-agent.1.lbx30ov89d2nhukviexnb32sz +hermes_hermes .11.9 + + +hermes_hermes-gateway.1.4ceprn5xwyd1jdvxk7r5i9mde +10.0.0.204 ingress · hermes_hermes .11.10 + + + +hermes_infra + +squid.1.l9zssq6kvlxwdw7ywlzri7miw +.108 ingress · squid_egress .12.11 · hermes_proxy .15.44 + + +sarg.1.ucvl44g6djt49y4fgfydmia4y +.107 ingress · admin .14.48 + + +hermes-ui.1.8mohposymmwn3sxcrupcf2a4h +.106 ingress · hermes_infra_default .13.16 · hermes_proxy .15.43 + + +hermes-gateway.1.vrbji4iqmw2e69zq1cbf2ooqb +hermes_proxy .15.47 + + +docker_socket_proxy.1.h80ql7v0epork75q3ij3h6gqf +admin .14.46 · hermes_proxy .15.46 + + +brencher-state-proxy (dead) +nginx_ingress · Replicas: 0 + + + +immich + +immich_server.1.a83c7oac6f4ukkzhae1tsj2ym +.225 ingress · immich_default .2.14 + + +immich_database.1.lstdz3kkogsrcg7vx7sae6rfa +.13 ingress · immich_default .2.6 + + +immich_redis.1.85hnh4elu9xxl9jcs64v4u0u2 +immich_default .2.8 + + +immich_machine-learning.1.wnkv2chqsfaq3st7a0qgezt7b +.11 ingress · immich_default .2.3 + + + +brencher + +brencher_brencher-backend.1.vdeqwr97iafplzieas71sq55a +.105 ingress · brencher-net .6.195 · brencher_default .7.195 · nginx_ingress .3.224 + + + +brencher2 + +brencher2_brencher-backend.1.ma4m7uabhe5lckk0fktaicf19 +.102 ingress · brencher2-net .5.12 · brencher2_default .1.12 · nginx_ingress .3.221 + + + +gmail_mcp + +gmail_mcp_gmail-mcp-server.1.wxhzdnibwssve5trbwffzyzpu +.10 ingress · gmail_mcp_default .8.6 + + +gmail_mcp_telegram-mcp-server.1.yehnql7ova2a65s6d6wly5y6m +.6 ingress · gmail_mcp_default .8.3 + + + +torrserv_proxy + +torrserv_proxy_reverseproxy.1.r906zcw2jyny6g6w56an1u193 +.15 ingress · torrserv_proxy_default .10.4 + + +torrserv_proxy_fileserver.1.zrum9hzhght93z9yxv0ae7hbs +.12 ingress · torrserv_proxy_default .10.3 + + + +nginx (dead) + +nginx_nginx (jwilder/nginx-proxy) +Replicas: 0 · no containers + + +nginx_nginx_acme (acme-companion) +Replicas: 0 + + + +photosHelper + +photosHelper_nfs_crypt +.9 ingress · photosHelper_default + + + +docker_socket_proxy + +docker_socket_proxy_hermes-gateway.1.kb09yigdxe9i7yqk9m0ecu2h5 +hermes_proxy .19.3 · dsp_default + + + +lampa-jackett (standalone, не swarm) + +lampa-jackett-1 +port 9117:9117 на хосте + + + + 4. INTERNAL NETS + только для своего стека + + + gitea_gitea + 10.0.17.0/24 + + + + immich_default + 10.0.2.0/24 + + + + hermes_hermes + 10.0.11.0/24 + + + + hermes_infra_default + 10.0.13.0/24 + + + + gmail_mcp_default + 10.0.8.0/24 + + + + torrserv_proxy_default + 10.0.10.0/24 + + + + brencher_brencher-net + 10.0.6.0/24 + + + + brencher_default + 10.0.7.0/24 + + + + brencher2_brencher-net + 10.0.5.0/24 + + + + brencher2_default + 10.0.1.0/24 + + + + photosHelper_default + 10.0.9.0/24 + + + + docker_socket_proxy_default + 10.0.21.0/24 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + LEGEND + + Client (tailscale) + + Keenetic / lan + + ingress / egress net + + internal net (stack-private) + + stack + + node (container) + + net connector (col 2) + + net connector (col 4) + + egress flow + + internal flow (col 3 -> col 4) + + node <-> network + + + + snapshot 2026-08-27 · 4 columns · 10 egress + 12 internal + 5 external · 12 stacks + + \ No newline at end of file