docs: observability stack + the single /_gm gate for Grafana/Mailpit
- 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:
@@ -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:-}`
|
||||
|
||||
Reference in New Issue
Block a user