4e97d8e5dc
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.
4.6 KiB
.claude/hooks — enforcement, not advice
CLAUDE.md files can only ask. These hooks are the part that enforces, and they
travel with the repo so a session started anywhere in this checkout gets them.
They are wired up in .claude/settings.json.
| Hook | Event | What it does |
|---|---|---|
prod-guard.sh |
PreToolUse | Live-host commands: reads run unprompted, mutations ask first |
secrets-guard.sh |
PreToolUse | Denies any direct write to infra/deploy/secrets/*.yaml |
lint-after-edit.sh |
PostToolUse | shellchecks an edited *.sh and feeds findings back immediately |
Why prod-guard exists
agent has passwordless sudo on vps1 and vps2, and the operator's global settings
allow Bash(ssh prod:*) outright. Nothing about ssh prod 'docker service rm …'
goes through a pull request, so CI cannot see it — before this hook, any session in
any directory could delete production with no prompt.
It classifies by allowlist, not blocklist. Only commands positively recognised as read-only are allowed through; everything else asks. A blocklist of dangerous verbs is wrong by construction — the first destructive verb nobody thought of sails straight through. Being wrong in the "ask" direction costs a keystroke; being wrong the other way costs production.
Beta is guarded as strictly as prod — more strictly than the names alone suggest,
now: vps2 (169.58.46.181) runs both prod and beta as separate Swarm stacks on
the same manager, sharing one TimescaleDB instance, so a "beta" command there has
prod's blast radius (see infra/deploy/env-topology.sh). vps1 (75.119.132.91) is
the other guarded host: Forgejo (git + CI + registry) and Grafana/Loki live there,
plus the dev environment, so a destructive command there takes out git, CI and the
registry at once. Mesh IPs did not move in the vps1/vps2 split (vps1 is still
10.10.0.2, vps2 is still 10.10.0.1); what moved is which environment runs where
— HOST_TOKEN_RE in prod-guard.sh recognises vps1/vps2 alongside the
environment names (prod/beta) and the raw IPs, so a command naming the host
either way still gets caught. The LAN dev box is deliberately unguarded.
Changing the classifier
is_readonly() in prod-guard.sh splits a command on &&, ||, ; and |, then
checks each segment's leading word. Redirection to a file, command substitution,
sed -i, and mutating docker/git/systemctl subcommands all count as writes.
If you add a command to the allowlist, re-run the test matrix. There is a
non-obvious failure mode this already hit once: the loop is fed by
printf '%s\n' | sed, and dropping that trailing newline makes read return
non-zero on the only line, so the loop body never runs and every command
classifies as read-only — a silent, total bypass that still looks like it works.
Test by piping a payload straight in:
echo '{"tool_name":"Bash","tool_input":{"command":"ssh prod '\''rm -rf /'\''"}}' \
| .claude/hooks/prod-guard.sh
# expect: permissionDecision "ask"
Exit 0 with no output means "no opinion" and the normal permission flow proceeds.
That is also what happens if jq is missing or the script errors, so a bug here
fails toward the prompt rather than toward silent execution.
lint-after-edit needs shellcheck on PATH
It exits quietly when shellcheck is absent — a missing local tool must not break
editing, and shell-lint CI is still the backstop. v0.11.0 (the version CI pins) is
installed at ~/.local/bin/shellcheck; if you move machines, reinstall it:
VER=v0.11.0
curl -fsSL "https://github.com/koalaman/shellcheck/releases/download/${VER}/shellcheck-${VER}.linux.x86_64.tar.xz" \
| tar -xJ --strip-components=1 -C ~/.local/bin "shellcheck-${VER}/shellcheck"
Keep it matched to shell-lint.yml's pin. A drifted shellcheck grows new warnings
and fails CI on an unrelated push, which is why that workflow pins the version and
its sha256 rather than using apt-get install.
The global copy
~/.claude/settings.json runs prod-guard.sh from ~/.claude/hooks/ as well, so a
session started outside this repo is covered too — otherwise the guard would be
trivially bypassed by working from ~/Code. That copy is a mirror; this one is
canonical. If you change the classifier here, copy it over:
cp .claude/hooks/prod-guard.sh ~/.claude/hooks/prod-guard.sh
The blanket Bash(ssh prod:*) / Bash(ssh beta:*) allow rules were removed from
global settings at the same time, so the hook is the only thing granting live-host
access. If it is missing or broken, nothing allows the command and you get a prompt.