docs(hermes_infra): pin gateway-channels mapping + terse README #29

Open
hermes wants to merge 1 commits from hermes/ansible:docs/hermes_infra-telegram-mapping into master
Contributor

Summary

Replace the stale hermes_squid/README.md (squid/blackboard notes) with a terse what/how-to-update/sources README, and add hermes_squid/docs/gateway-channels.md recording the chat-id ↔ service mapping across the two Telegram-using stacks (hermes_infra and hermes) plus the disconnected docker_socket_proxy gateway.

Why

admin/ansible#26 investigates the prod gateway interruption. While tracing the chat-id the agent learned:

  • hermes_infra_hermes-gateway answers chat -1004417969359 (Home).
  • hermes_hermes-gateway (separate hermes stack under poc/) answers chat -1004355191149.
  • docker_socket_proxy_hermes-gateway is up but platforms={} — not connected.

The two live gateways are in different compose files but share the same service name (hermes-gateway) and the same image (nousresearch/hermes-agent:v2026.8.3). Anyone editing hermes_infra/stack-compose.yml while blind to poc/hermes/stack-compose.yml risks merging the two, which would cause both stacks to double-connect to a chat and double-respond.

A future reader without context could mistake the second gateway for the prod one and "consolidate" the compose files, breaking both bots. The README + docs/gateway-channels.md make that risk visible.

Diff

  • hermes_squid/README.md: 27 lines → 16 lines, recontextualised to the prod stack, no narrative.
  • hermes_squid/docs/gateway-channels.md: new, 1.6 KB, single source of truth for chat-id ↔ service table.

Sources

  • Live chat-id was pulled via docker exec ... cat /opt/data/gateway_state.json | jq '.platforms.telegram.chat_id' for each container (not committed in repo).
  • Cross-stack map was confirmed via brencher container logs (image revision column) on 30.08.2026.

Test plan

Render-only change. No deploy step. Verify by:

  1. git ls-files hermes_squid/ lists README.md, docs/gateway-channels.md, stack-compose.yml.
  2. Open https://gitea.rudolf.keenetic.link/admin/ansible/src/master/hermes_squid/docs/gateway-channels.md — table renders.
  3. Cross-read with poc/hermes/stack-compose.yml outside this PR — the new README explicitly says "do not mix", matching the structure.

Rollback

Documentation; revert commits or push a new branch closing the mapping.

Refs: admin/ansible#26.

## Summary Replace the stale `hermes_squid/README.md` (squid/blackboard notes) with a terse what/how-to-update/sources README, and add `hermes_squid/docs/gateway-channels.md` recording the chat-id ↔ service mapping across the two Telegram-using stacks (`hermes_infra` and `hermes`) plus the disconnected `docker_socket_proxy` gateway. ## Why `admin/ansible#26` investigates the prod gateway interruption. While tracing the chat-id the agent learned: - `hermes_infra_hermes-gateway` answers chat **-1004417969359** (Home). - `hermes_hermes-gateway` (separate `hermes` stack under `poc/`) answers chat **-1004355191149**. - `docker_socket_proxy_hermes-gateway` is up but `platforms={}` — not connected. The two live gateways are in different compose files but share the **same service name** (`hermes-gateway`) and the **same image** (`nousresearch/hermes-agent:v2026.8.3`). Anyone editing `hermes_infra/stack-compose.yml` while blind to `poc/hermes/stack-compose.yml` risks merging the two, which would cause both stacks to double-connect to a chat and double-respond. A future reader without context could mistake the second gateway for the prod one and "consolidate" the compose files, breaking both bots. The README + docs/gateway-channels.md make that risk visible. ## Diff - `hermes_squid/README.md`: 27 lines → 16 lines, recontextualised to the prod stack, no narrative. - `hermes_squid/docs/gateway-channels.md`: new, 1.6 KB, single source of truth for chat-id ↔ service table. ## Sources - Live chat-id was pulled via `docker exec ... cat /opt/data/gateway_state.json | jq '.platforms.telegram.chat_id'` for each container (not committed in repo). - Cross-stack map was confirmed via brencher container logs (image revision column) on 30.08.2026. ## Test plan Render-only change. No deploy step. Verify by: 1. `git ls-files hermes_squid/` lists `README.md`, `docs/gateway-channels.md`, `stack-compose.yml`. 2. Open `https://gitea.rudolf.keenetic.link/admin/ansible/src/master/hermes_squid/docs/gateway-channels.md` — table renders. 3. Cross-read with `poc/hermes/stack-compose.yml` outside this PR — the new README explicitly says "do not mix", matching the structure. ## Rollback Documentation; revert commits or push a new branch closing the mapping. Refs: `admin/ansible#26`.
hermes added 1 commit 2026-08-30 23:42:43 +02:00
The prod hermes-gateway (stack=hermes_infra, chat-id=-1004417969359)
and a separate poc gateway (stack=hermes, chat-id=-1004355191149)
share the same service name in two compose files. Anyone editing
hermes_infra/stack-compose.yml without seeing the poc compose risks
scaling the wrong stack or merging the two into one compose — which
would double-respond to inbound Telegram messages and make
'interrupted by user message' warnings meaningless.

This change replaces the stale squid/blackboard README with a terse
one (what / how to update / pitfall) and adds a sibling doc that
records the current chat-id ↔ service mapping. Future changes must
keep that table consistent.

Refs admin/ansible#26.
Checking for merge conflicts…
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u https://gitea.rudolf.keenetic.link/hermes/ansible docs/hermes_infra-telegram-mapping:hermes-docs/hermes_infra-telegram-mapping
git checkout hermes-docs/hermes_infra-telegram-mapping
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: admin/ansible#29