4e97d8e5dc
All checks were successful
PR build (required check) / changes (pull_request) Successful in 6s
secrets-guard / encrypted (pull_request) Successful in 5s
PR build (required check) / build-backend (pull_request) Has been skipped
shell-lint / shellcheck (pull_request) Successful in 7s
PR build (required check) / build-frontend (pull_request) Has been skipped
PR build (required check) / validate-observability (pull_request) Successful in 18s
PR build (required check) / gate (pull_request) Successful in 2s
Environments stop being machines. Until now each box WAS an environment --
"beta" named both a deploy target and a host, "the desktop" named both the
operator's computer and the dev server -- so every path could assume one
environment per host and hardcode /opt/thermograph, /etc/thermograph.env and
ports 8137/8080. That assumption ends here:
vps1 75.119.132.91 Forgejo, Grafana/Loki, the portfolio site, and DEV
(own Postgres, mesh-only on 10.10.0.2:8137)
vps2 169.58.46.181 PROD and BETA as two Swarm stacks sharing one
TimescaleDB instance, plus Centralis, Postfix, backups
desktop AI model hosting + flex Swarm capacity, no environment
Nothing live has moved; the ordered cutover is in
infra/deploy/RUNBOOK-vps1-vps2-cutover.md.
deploy/env-topology.sh is the single source of truth: env -> host, checkout,
branch, deploy mode, stack name, env file, LB ports, DB role/database, service
prefix. THERMOGRAPH_ENV is the input, and on vps2 it is the only thing
distinguishing a beta deploy from a prod one -- deploy.sh refuses to run when it
disagrees with the checkout it was invoked from. The host-wide secrets-env and
deploy-mode markers survive only as a fallback for a single-environment box.
Beta gets its own stack file rather than an overlay (a merge cannot REMOVE the
db service, and beta having no database of its own is the point). Its services
are prefixed beta-*: Swarm registers a service's short name as a DNS alias on
every network it joins, so two stacks both calling a service `web` on the shared
data network would let prod's frontend resolve a beta task. Prod's stack, env
and LB config are untouched.
One Postgres, two databases with two roles: deploy/db/provision-env-db.sh
creates thermograph_beta (NOSUPERUSER, owns only its own database, CONNECT
revoked from PUBLIC) plus a <role>_ro for ad-hoc queries, and refuses to run for
the environment that owns the instance -- doing so would demote prod's bootstrap
superuser.
Fixes that co-residency would otherwise have broken silently:
- CI secrets are keyed by host (VPS1_SSH_*, VPS2_SSH_*). SSH_* meant "beta" and
also "the Forgejo box" because those shared a machine; that conflation is what
once had the prod backup dumping beta.
- The nightly backup dumps BOTH application databases to separate off-box
prefixes, and fails loudly on a missing one instead of skipping it.
- Alloy stopped deriving the `host` label from the node -- on vps2 that would
have filed every beta line as prod, feeding prod's alert rules with beta's
traffic. It is now derived per source, with a new `node` label for the machine,
and beta's log volume is mounted via a vps2-only overlay.
- ops/dbq.sh, ops/iceberg.sh and the secrets seed scripts derived their SSH
target and env-file path from the topology instead of hardcoding beta to
75.119.132.91 -- which is vps1's address now.
- Dev's overlay binds DEV_BIND_ADDR (loopback by default, the mesh address on
vps1) instead of 0.0.0.0: correct for a home LAN box, a public exposure of
unreviewed branches on a VPS.
Terraform's hosts variable is keyed by machine with a nested environments map,
and main.tf flattens (host, environment) pairs so two environments on one box
cannot share a checkout. Caddy's single reference config is split per host.
Docs, onboarding and the runbooks are updated throughout, including the security
rationales that co-residency makes false: separate SSH credentials no longer put
a host boundary between beta and prod, and the boundary that remains is the
database and the filesystem.
3.5 KiB
3.5 KiB
observability/ — agent instructions
The logging stack for the fleet: Loki + Grafana on vps1 — the monitoring
host, mesh 10.10.0.2, and NOT the beta environment (that runs on vps2 now;
any doc that still says "beta" meaning this box is stale) — with a Grafana
Alloy agent on every node shipping container and app logs over the WireGuard
mesh. vps1 also hosts Forgejo, the portfolio site, and the dev environment
(mesh-only, no public DNS). vps2 runs prod and beta as two Swarm stacks.
Grafana is fronted by vps1's Caddy at dashboard.thermograph.org (Google
SSO, pre-provisioned users only) — use that hostname everywhere, never
grafana.thermograph.org.
This is operational config, not application code: there is no build and no
deploy automation. It ships by hand — docker compose up -d on vps1 for
Loki+Grafana, and alloy/docker-compose.agent.yml on each node. Read the root
CLAUDE.md first; the branch model there applies here too.
Layout
docker-compose.yml— the Loki + Grafana stack (vps1).loki/config.yml— mesh-only, filesystem storage.grafana/provisioning/— datasource + dashboard provider, auto-loaded at startup.grafana/dashboards/*.json— the dashboards.grafana/provisioning/alerting/— alert rules, the Discord contact point, and the notification policy.alloy/config.alloy+alloy/docker-compose.agent.yml(+alloy/docker-compose.agent.beta.yml, a vps2-only overlay adding beta'sapplogsmount) — the per-node shipper.ALLOY_NODEis the MACHINE (vps1|vps2|desktop) — that's a semantic change from when the fleet had one environment per node;host(prod|beta|dev), the ENVIRONMENT label every dashboard/alert slices on, is now derived per source instead, since vps2 alone carries two of them.caddy-grafana.conf— the vps1 Caddy vhost, kept here for reference..env.example— copy to.envon vps1..envis gitignored; never commit OAuth secrets or the admin password.
Rules
- The repo is the only durable path. Dashboards and alerting are provisioned from this directory at startup; edits made through Grafana's UI or API are overwritten on the next provision. Changes go through a PR.
- Every artifact that ships to a node is CI-validated
(
.forgejo/workflows/observability-validate.yml, at the repo root): both compose files parse, all dashboard JSON is valid, the Loki and provisioning YAML parse, and the Alloy config is checked with the pinnedalloybinary (v1.9.1, matching what the fleet runs). - Alerting gets a stricter third step. Every rule's
conditionmust name a refId that exists, every policy must route to a receiver that exists, and a literal Discord webhook URL in the repo is a hard failure. A rule pointing at a missing refId is valid YAML, provisions cleanly, and then never fires — that silent no-op is what this check exists to prevent. - Alerts go to Discord
#ops-alerts, never email. vps1's Grafana relays SMTP through vps2's Postfix, so email dies exactly when prod (on vps2) does. - Every rule is LogQL — there is no Prometheus anywhere in the fleet. Thresholds were derived from real Loki data and the working is in the comments beside each rule; re-derive before changing a number rather than guessing.
- Secrets (OAuth client id/secret, admin password) live only in the host
.env.
Commits & PRs
Concise and technical. Never mention AI, assistants or automated authorship.