docs: observability stack + the single /_gm gate for Grafana/Mailpit
Tests · Go / test (pull_request) Successful in 1m56s
Tests · Integration / integration (pull_request) Successful in 1m41s
Tests · UI / test (pull_request) Successful in 3m23s

- ARCHITECTURE §17: the dev (production-mirror) collection stack
  (Prometheus / Loki / Tempo / promtail / node-exporter / cAdvisor) and
  the single /_gm Basic Auth gate fronting Grafana and the Mailpit UI.
- tools/dev-deploy/monitoring/README.md (new): services, what is
  collected, Grafana-behind-the-gate access, config delivery, tuning.
- tools/dev-deploy/README.md: an Observability section; the Mailpit UI
  under /_gm/mailpit/; Networking diagram and Files list updated.
- FUNCTIONAL §10.2.1 (+ ru mirror): the operator console nav links to
  Grafana and Mailpit under the same /_gm gate, one sign-in for all.
This commit is contained in:
Ilia Denisov
2026-06-01 06:37:24 +02:00
parent cb8491c200
commit 814eae0802
5 changed files with 140 additions and 5 deletions
+43 -3
View File
@@ -148,6 +148,38 @@ With none set the stack only captures mail (the compose relay-match
defaults to a non-routable address), so it can never email third
parties.
The capture UI is exposed through the operator console's `/_gm` gate at
[`/_gm/mailpit/`](https://galaxy.lan/_gm/mailpit/) — one Basic Auth for
the console, Grafana and Mailpit (see **Observability**). It shows
**every** message the backend sent, relayed or not, so you can read any
account's OTP regardless of the relay-match. For multi-account testing:
register several `you+tag@gmail.com` aliases and widen the match to a
regex such as `^you(\+[^@]+)?@gmail\.com$` (Gmail folds every `+tag`
into one inbox), or just read the codes in the Mailpit UI, or skip mail
entirely with the `123456` dev-code.
## Observability
A full metrics + logs + traces stack runs alongside the app on the
internal network (no host ports), as a production mirror. **Grafana**
and the **Mailpit** UI are reached only through the operator console's
single `/_gm` Basic Auth gate — one password (the admin-console account)
unlocks the console, [`/_gm/grafana/`](https://galaxy.lan/_gm/grafana/)
and [`/_gm/mailpit/`](https://galaxy.lan/_gm/mailpit/), with links in the
console nav. Grafana runs anonymous-Admin behind the gate (no own
login); Prometheus, Loki and Tempo stay internal-only.
- **Metrics** — Prometheus scrapes backend, gateway, `node-exporter` and
cAdvisor.
- **Logs** — promtail → Loki (Docker SD on the `galaxy.stack=dev-deploy`
label).
- **Traces** — backend + gateway → Tempo over OTLP.
Grafana's admin user is seeded from `GALAXY_DEV_GRAFANA_ADMIN_PASSWORD`
(for provisioning/API; the UI needs no Grafana login). See
[`monitoring/README.md`](monitoring/README.md) for services, configs and
tuning knobs.
## Networking
```
@@ -162,6 +194,8 @@ galaxy-caddy (networks: edge + galaxy-dev-internal)
│ /game/* -> file_server /srv/galaxy-ui (volume galaxy-dev-ui-dist)
│ /api/*, /healthz -> reverse_proxy galaxy-api:8080
│ /rpc/* -> reverse_proxy galaxy-api:9090 (strips /rpc)
│ /_gm, /_gm/* -> reverse_proxy galaxy-api:8080 (Basic Auth gate;
│ /_gm/grafana/ -> grafana, /_gm/mailpit/ -> mailpit)
galaxy-dev-internal
├─ galaxy-api (gateway: :8080 REST, :9090 gRPC)
@@ -169,7 +203,9 @@ galaxy-dev-internal
├─ galaxy-postgres (postgres: :5432)
├─ galaxy-redis (redis: :6379)
├─ galaxy-mailpit (mailpit: :8025 UI, :1025 SMTP)
─ engine containers (spawned by backend on demand)
─ engine containers (spawned by backend on demand)
└─ observability (prometheus, grafana, loki, promtail, tempo,
node-exporter, cadvisor)
```
The compose project deliberately exposes no host ports. Diagnostics
@@ -214,8 +250,10 @@ make clean-data Stop everything and wipe volumes + game-state dir
## Files
- `docker-compose.yml` — six services: postgres, redis, mailpit,
galaxy-backend, galaxy-api, galaxy-caddy. `galaxy-caddy` mounts both
- `docker-compose.yml` — the application services (postgres, redis,
mailpit, galaxy-backend, galaxy-api, galaxy-caddy) plus the
observability stack (prometheus, grafana, loki, promtail, tempo,
node-exporter, cadvisor). `galaxy-caddy` mounts both
the `galaxy-dev-site-dist` (`/srv/galaxy-site`) and
`galaxy-dev-ui-dist` (`/srv/galaxy-ui`) volumes and reverse-proxies
both gateway tiers (REST/health on `:8080`, Connect/gRPC-web on
@@ -227,6 +265,8 @@ make clean-data Stop everything and wipe volumes + game-state dir
at `/etc/caddy/Caddyfile`.
- `Caddyfile.prod` — placeholder for a future prod deployment; not used
by this compose.
- `monitoring/` — Prometheus / Loki / promtail / Tempo / Grafana
configuration, provisioned as code; see `monitoring/README.md`.
- `Makefile` — wrapper over `docker compose` with helpers for engine,
site/UI seeding, health probes, and full wipe.
- `.env.example` — non-secret defaults for the compose `${VAR:-}`