4e97d8e5dc
All checks were successful
PR build (required check) / changes (pull_request) Successful in 6s
shell-lint / shellcheck (pull_request) Successful in 7s
secrets-guard / encrypted (pull_request) Successful in 5s
PR build (required check) / build-backend (pull_request) Has been skipped
PR build (required check) / build-frontend (pull_request) Has been skipped
PR build (required check) / gate (pull_request) Successful in 2s
PR build (required check) / validate-observability (pull_request) Successful in 18s
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.
165 lines
8.6 KiB
Markdown
165 lines
8.6 KiB
Markdown
# 1. Orientation
|
||
|
||
## What the product actually claims
|
||
|
||
Thermograph answers one question: **how unusual is the weather here, right now,
|
||
compared to this exact place's own history?**
|
||
|
||
That framing is not decoration — it constrains the code, the copy and the
|
||
colour scales:
|
||
|
||
- A grade is a **percentile against ~45 years of that grid cell's own record**,
|
||
not an absolute reading. 60 °F is *Above Normal* on a cool coast and *Below
|
||
Normal* inland on the same afternoon.
|
||
- Tier names are therefore relative words — *Near Record*, *High*, *Above
|
||
Normal*, *Normal*, *Below Normal*, *Low*, *Near Record* — never "hot",
|
||
"warm", "cold". This rule binds prose, alt text, commit messages and API
|
||
fields alike.
|
||
- Precipitation is graded on its **own** ladder, because most days are dry: a
|
||
rainy day is ranked only among the rain days in its seasonal window, and dry
|
||
days are coloured by dry-streak length instead.
|
||
|
||
Public since **2026-07-16**. Free. Run by one operator plus automation, which
|
||
is why so much of this repo is about making irreversible things hard.
|
||
|
||
## The domain model, in six steps
|
||
|
||
1. **Grid** (`backend/data/grid.py`) — an arbitrary lat/lon snaps to a stable
|
||
**~4 sq mi cell**. Latitude rows are ~2 miles tall; longitude spacing scales
|
||
by `cos(latitude)` so cells stay roughly square at any latitude. The cell id
|
||
is deterministic and is the cache key for everything downstream. Worldwide
|
||
coverage, no gaps.
|
||
2. **History** (`backend/data/climate.py`) — the full **1980 → present daily
|
||
record** (max/min temp, precip, wind, gust, humidity, feels-like) for that
|
||
cell, fetched once and stored durably. Expensive to obtain, so it is treated
|
||
as source-of-truth data, not cache.
|
||
3. **Recent + forecast** — a separate bundle of recent observations plus ~8
|
||
forward days, refreshed on its own TTL. This is what "today" is graded from.
|
||
4. **Grading** (`backend/data/grading.py`) — for a given day of year, the
|
||
reference distribution is *every historical day within ±7 days of it*
|
||
(a 15-day seasonal window that wraps the year end). The observed value is
|
||
placed on that distribution as an **empirical mid-rank percentile**, then
|
||
mapped onto `TEMP_BANDS` / `RAIN_BANDS`.
|
||
5. **Payloads** (`backend/api/payloads.py`) — pure "inputs → response dict"
|
||
assembly. One definition per payload shape, shared by the HTTP routes, the
|
||
`/cell` bundle and offline tooling.
|
||
6. **Caching** (`backend/data/store.py`) — every derived payload is stored
|
||
against a **validity token** that encodes everything the payload depends on.
|
||
A token mismatch is simply a miss. Freshness is driven by the token
|
||
advancing, *never* by clock expiry — so stale data cannot be served, and one
|
||
`PAYLOAD_VER` bump atomically orphans every pre-upgrade row.
|
||
|
||
If you internalise one thing: **the token is the cache-correctness mechanism,
|
||
and `PAYLOAD_VER` is the lever that moves it.** See
|
||
[contracts](06-contracts.md).
|
||
|
||
## The estate
|
||
|
||
Hosts are named by **role**, not by environment, plus the operator's desktop —
|
||
all on a WireGuard mesh (`10.10.0.0/24`):
|
||
|
||
| Host | Mesh IP | Public | Runs |
|
||
|---|---|---|---|
|
||
| **vps1** | `10.10.0.2` | `75.119.132.91`, git.thermograph.org, dashboard.thermograph.org | Forgejo (git + CI + registry), Grafana + Loki + Alloy, the `emigriffith.dev` portfolio, and **dev** — its own Postgres, plain compose, **mesh-only** (no public DNS, no Caddy site, no TLS) |
|
||
| **vps2** | `10.10.0.1` | `169.58.46.181`, thermograph.org, beta.thermograph.org | **prod** and **beta** as two separate Docker **Swarm** stacks, Centralis, Postfix, backups |
|
||
| **desktop** | `10.10.0.3` | — | AI-model hosting (voice-to-text, an upcoming-feature LLM) + flex Swarm capacity. Hosts **no** Thermograph environment — `make dev-up` there is a laptop convenience only |
|
||
| phone | — | — | alerts |
|
||
|
||
vps2 runs prod and beta **co-resident on one box**: one TimescaleDB instance
|
||
serves both, on separate databases and separate roles (`thermograph` /
|
||
`thermograph_beta`, the latter `NOSUPERUSER`/`NOCREATEDB`, `CONNECT` revoked
|
||
from `PUBLIC`); separate checkouts, env files and loopback LB ports; beta's
|
||
Swarm service names are prefixed (`beta-web`, not `web`) because Swarm
|
||
registers a service's short name as a DNS alias on every network it joins, and
|
||
beta shares prod's network to reach the database. Beta rehearses prod's actual
|
||
orchestrator this way — that's the point of putting it next to prod rather
|
||
than next to dev.
|
||
|
||
The mesh IPs did not move when this topology landed — vps1 is the box that used
|
||
to be called "beta", vps2 the one that used to be called "prod". What moved is
|
||
which environment lives where. `infra/deploy/env-topology.sh` is the single
|
||
source of truth for every per-environment path, port and role; `THERMOGRAPH_ENV`
|
||
(`dev`/`beta`/`prod`) is the input a deploy leg passes, since vps2 can no longer
|
||
tell beta and prod apart by which host it's running on.
|
||
|
||
Two consequences you will hit within the first week:
|
||
|
||
- **Forgejo is mesh-only.** `git.thermograph.org` resolves publicly to vps1's
|
||
IP, but vps1's Caddy rejects `/v2/*` (the registry API) from outside the
|
||
mesh. Any host that pulls images needs `10.10.0.2 git.thermograph.org` in
|
||
`/etc/hosts`.
|
||
- **Beta and prod run the same orchestrator now — Swarm, as two stacks on one
|
||
box.** Dev is the only environment on compose (`infra/docker-compose.yml`),
|
||
and it lives alone on vps1. Most of the time you don't care which stack
|
||
you're reading — but when you're reading logs or naming containers, you do
|
||
(see [observability](09-observability.md)), and on vps2 you additionally have
|
||
to say *which* environment: `deploy.sh` there routes on the explicit
|
||
`THERMOGRAPH_ENV` a caller passes, not on which host it's running on.
|
||
|
||
## How a change travels
|
||
|
||
```
|
||
PR ──(required check: `gate`)──▶ dev ──▶ dev (vps1, mesh-only)
|
||
│
|
||
promotion PR
|
||
▼
|
||
main ──▶ beta.thermograph.org (vps2)
|
||
│
|
||
promotion PR ← the owner's call
|
||
▼
|
||
release ──▶ thermograph.org (vps2)
|
||
```
|
||
|
||
`dev`, `main` and `release` are **protected** — no direct pushes, for humans or
|
||
agents. Promotion is by pull request, continuously and per-decision; there is
|
||
no release calendar. Full detail in [CI and release](07-ci-and-release.md).
|
||
|
||
## The four rules that are not negotiable
|
||
|
||
These come from the operator, via Centralis's own onboarding. They override
|
||
convenience.
|
||
|
||
1. **Everything is a PR.** If it didn't go through the pipeline, it didn't
|
||
happen. This includes Grafana dashboards (provisioned from repo JSON — a UI
|
||
edit is silently overwritten) and secrets (SOPS vault only).
|
||
2. **Boring prod.** Anything clever proves itself on `dev` or beta first.
|
||
3. **Privacy is a feature.** No tracking cookies, no per-visitor IDs,
|
||
allowlisted anonymous counters only (`backend/core/metrics.py`,
|
||
`POST /api/v2/event`). Cheap to keep, expensive to retrofit.
|
||
4. **Grades are relative.** Never describe a percentile as hot or cold.
|
||
|
||
### And a fifth, local to the repo
|
||
|
||
**Commits and PRs are concise and technical, and never mention AI, assistants
|
||
or automated authorship.** Every domain `CLAUDE.md` says this; it applies to
|
||
you too.
|
||
|
||
## Quota discipline
|
||
|
||
Thermograph runs on free upstream data sources. Two hard rules protect them:
|
||
|
||
- **Anything named "prefetch" or "warm" must never spend the Open-Meteo
|
||
quota.** The warming paths call `climate.load_cached_history` /
|
||
`load_cached_recent_forecast` — the cache-only loaders — and skip cells that
|
||
aren't warm. A cell self-heals on first real request instead.
|
||
- **Nominatim gets at most ~1 request/second.** All reverse geocoding funnels
|
||
through a single dedicated worker thread
|
||
(`climate._revgeo_worker`) that paces itself; never call it from a request
|
||
thread.
|
||
|
||
Breaking either one gets the whole service rate-limited, which is why
|
||
`singleton.claim_leader()` exists: a background sweep running in N uvicorn
|
||
workers × M hosts multiplies quota use by N×M. That failure has already
|
||
happened once, in production, at 3 workers.
|
||
|
||
## Where the written record lives
|
||
|
||
| Question | Where |
|
||
|---|---|
|
||
| How does this repo work? | The domain `CLAUDE.md` files, then this set |
|
||
| Why is the architecture like this? | `thermograph-docs` (ADRs) — `docs_search` |
|
||
| How do I operate the fleet? | `thermograph-docs` runbooks, plus the `thermograph-ops` Centralis skill |
|
||
| What did someone find out last Tuesday? | `notes_search` |
|
||
| What is and isn't live yet? | [`CUTOVER-NOTES.md`](../../CUTOVER-NOTES.md) at the repo root |
|
||
|
||
Next: [Local setup](02-setup.md).
|