2026-07-23 05:11:33 +00:00
|
|
|
# thermograph monorepo — agent instructions
|
|
|
|
|
|
2026-07-25 07:08:54 +00:00
|
|
|
One repo, four domains: `backend/`, `frontend/`, `infra/`, `observability/`.
|
|
|
|
|
Reunified 2026-07-22 from four split repos, with history, via subtree merges.
|
|
|
|
|
`thermograph-docs` is deliberately a separate repo — cross-cutting decision
|
|
|
|
|
records and operator runbooks go there, not here.
|
|
|
|
|
|
|
|
|
|
**Rule for this file and every domain `CLAUDE.md`: only statements that would
|
|
|
|
|
break CI if they became false, or that name a file that exists.** Background,
|
|
|
|
|
history and rationale belong in `thermograph-docs`. These files are read before
|
|
|
|
|
every change, so a stale one is a correctness bug, not a documentation bug.
|
|
|
|
|
|
|
|
|
|
## Branches and environments
|
|
|
|
|
|
|
|
|
|
| Branch | Deploys to | Workflow |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| feature branch | nothing | PR into `dev` |
|
infra: split the estate into vps1/vps2, moving beta next to prod and dev onto vps1
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.
2026-07-25 22:01:29 +00:00
|
|
|
| `dev` | dev (vps1, mesh-only, own Postgres) | `deploy.yml` |
|
|
|
|
|
| `main` | beta (beta.thermograph.org, vps2) | `deploy.yml` |
|
|
|
|
|
| `release` | prod (thermograph.org, vps2) | `deploy.yml` |
|
2026-07-25 07:08:54 +00:00
|
|
|
|
|
|
|
|
`dev`, `main` and `release` are protected: **everything is a PR**, for humans and
|
|
|
|
|
agents alike. Promotion is one PR per hop, `dev` → `main` → `release`.
|
|
|
|
|
|
infra: split the estate into vps1/vps2, moving beta next to prod and dev onto vps1
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.
2026-07-25 22:01:29 +00:00
|
|
|
**`dev` is a first-class hosted environment, not just an integration branch.**
|
|
|
|
|
It runs on vps1 — the same box as Forgejo and the monitoring stack — with its
|
|
|
|
|
own Postgres container, reachable only on the WireGuard mesh
|
|
|
|
|
(`10.10.0.2:8137`): no public DNS record, no Caddy site, no TLS. It is deployed
|
|
|
|
|
by CI like beta and prod. The desktop hosts no Thermograph environment at all;
|
|
|
|
|
`make dev-up` there is a laptop convenience for running the stack locally, not
|
|
|
|
|
a deployment target.
|
|
|
|
|
|
|
|
|
|
**One workflow deploys everything.** `deploy.yml` handles both services and all
|
|
|
|
|
three environments: the branch selects the environment (`dev` → vps1, `main` →
|
|
|
|
|
beta on vps2, `release` → prod on vps2), a matrix covers backend and frontend,
|
|
|
|
|
and each leg checks whether this push actually touched its domain before
|
|
|
|
|
rolling. `build-push.yml` is the same shape for images. `THERMOGRAPH_ENV` is the
|
|
|
|
|
input that tells a leg which environment it's deploying — load-bearing on vps2,
|
|
|
|
|
which runs beta and prod side by side and has no other way to tell them apart.
|
|
|
|
|
See `infra/deploy/env-topology.sh` for the single source of truth on where each
|
|
|
|
|
environment's checkout, branch, stack and ports live.
|
2026-07-25 07:08:54 +00:00
|
|
|
|
|
|
|
|
## The deploy contract
|
|
|
|
|
|
|
|
|
|
One entry point, two modes, one contract:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
SERVICE=backend|frontend|all BACKEND_IMAGE_TAG=sha-<12hex> FRONTEND_IMAGE_TAG=sha-<12hex> \
|
|
|
|
|
/opt/thermograph/infra/deploy/deploy.sh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`deploy.sh` resets the host checkout, renders secrets from the SOPS vault, then
|
infra: split the estate into vps1/vps2, moving beta next to prod and dev onto vps1
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.
2026-07-25 22:01:29 +00:00
|
|
|
either rolls compose services or — if `infra/deploy/env-topology.sh` says the
|
|
|
|
|
environment's deploy mode is `stack` — execs `infra/deploy/stack/deploy-stack.sh`.
|
|
|
|
|
The old host-wide `/etc/thermograph/deploy-mode` marker survives only as a
|
|
|
|
|
fallback for a by-hand run with no environment resolvable any other way; it
|
|
|
|
|
cannot describe vps2 alone, since vps2 runs beta and prod side by side.
|
|
|
|
|
|
|
|
|
|
- **prod and beta both run Swarm, as two separate stacks co-resident on vps2.**
|
|
|
|
|
Prod's is `infra/deploy/stack/thermograph-stack.yml` (db, web, worker, lake,
|
|
|
|
|
daemon, frontend, autoscaler, autoscaler-lake). Beta's is the separate
|
|
|
|
|
`infra/deploy/stack/thermograph-beta-stack.yml` — its services are prefixed
|
|
|
|
|
(`beta-web`, `beta-worker`, …) because Swarm registers a service's short name
|
|
|
|
|
as a DNS alias on every network it joins, and beta shares prod's `data`
|
|
|
|
|
network to reach the database. Beta has no `db` service of its own: one
|
|
|
|
|
TimescaleDB instance serves both, on separate databases and separate
|
|
|
|
|
NOSUPERUSER roles. `deploy-stack.sh` also offers `STACK_TEST=1`: a full
|
|
|
|
|
parallel rehearsal on throwaway volumes and ports that cannot touch live data.
|
|
|
|
|
- **dev runs compose**, from `infra/docker-compose.yml` (db, backend, lake,
|
|
|
|
|
daemon, frontend), on its own host (vps1) with its own Postgres container —
|
|
|
|
|
the one environment not sharing a database with anything else.
|
2026-07-25 07:08:54 +00:00
|
|
|
- Each service's live tag is persisted host-side, so a single-service roll never
|
|
|
|
|
disturbs the sibling's running tag.
|
|
|
|
|
|
|
|
|
|
Images are `emi/thermograph/backend` and `emi/thermograph/frontend`, tagged
|
|
|
|
|
`sha-<12hex>` on every push and by semver on `v*.*.*` tags. They build and deploy
|
|
|
|
|
**independently** — a backend change ships without a frontend deploy and vice
|
|
|
|
|
versa. That independence is the point of the FE/BE split and survived
|
|
|
|
|
reunification.
|
|
|
|
|
|
|
|
|
|
## Rules that bind across domains
|
|
|
|
|
|
|
|
|
|
- **CI lives only in root `.forgejo/workflows/`**, path-filtered per domain.
|
|
|
|
|
Never add workflows under a domain's own `.forgejo/` — they are inert there and
|
|
|
|
|
become a trap.
|
|
|
|
|
- **Secrets only via the SOPS vault** (`infra/deploy/secrets/`). Never hand-edit
|
|
|
|
|
`/etc/thermograph.env` on a host — it is a rendered artifact. `secrets-guard`
|
|
|
|
|
CI rejects plaintext. `seed-from-live.sh` reads production secrets and is
|
|
|
|
|
explicitly **not** for an agent to run.
|
|
|
|
|
- FE and BE ship out of lockstep, so the `/api/version` contract and
|
|
|
|
|
`PAYLOAD_VER` discipline are load-bearing — see `backend/CLAUDE.md`.
|
|
|
|
|
- Anything named "prefetch" must never spend the Open-Meteo quota.
|
|
|
|
|
Nominatim ≤ 1 req/s.
|
2026-07-23 05:11:33 +00:00
|
|
|
- The compose project name is pinned (`name: thermograph` in
|
infra: split the estate into vps1/vps2, moving beta next to prod and dev onto vps1
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.
2026-07-25 22:01:29 +00:00
|
|
|
`infra/docker-compose.yml`); dev (and a local `make dev-up`) overrides with
|
2026-07-25 07:08:54 +00:00
|
|
|
`COMPOSE_PROJECT_NAME=thermograph-dev`. Don't remove either half — the pinned
|
|
|
|
|
name is what makes the Swarm stack's external volume names line up.
|
2026-07-23 05:11:33 +00:00
|
|
|
- `CUTOVER-NOTES.md` is the source of truth for what is and isn't live yet.
|
2026-07-25 07:08:54 +00:00
|
|
|
|
|
|
|
|
## Commits & PRs
|
|
|
|
|
|
|
|
|
|
Describe only the substance of the change; concise and technical. Never mention
|
|
|
|
|
AI, Claude, assistants or automated authorship anywhere — no trailers,
|
|
|
|
|
co-authors, emoji, or "as requested" narration.
|
