thermograph/infra/CLAUDE.md

infra/ — agent instructions

How and where the already-built app images run: Terraform, the SOPS+age secrets vault, compose and Swarm stack files, deploy scripts, host provisioning, mail, and the ops cron (DB backup + IndexNow). Read the root CLAUDE.md first — it owns the branch model, the deploy contract, and which environment runs which orchestrator.

The machines

Per ACCESS.md: dev (operator's box — LAN dev server and CI runner), prod (169.58.46.181, thermograph.org, agent user, passwordless sudo), beta (75.119.132.91, beta.thermograph.org + Forgejo + Grafana/Loki, agent user). All four are on a WireGuard mesh. Hosts' /opt/thermograph is a checkout of this monorepo, not an infra-only repo.

Deploy paths

• deploy/deploy.sh — the single entry point for beta and prod. Resets the host checkout to BRANCH (default main), renders secrets, then routes: if /etc/thermograph/deploy-mode says stack it execs deploy/stack/deploy-stack.sh, otherwise it rolls compose services. Per-service tags persist in untracked deploy/.image-tags.env (compose) and deploy/.stack-image-tags.env (stack) so the two never mix.
• deploy/stack/deploy-stack.sh — the Swarm path, live on prod. backend rolls web and worker; frontend rolls frontend; all runs a full docker stack deploy. Start-first, health-gated, auto-rollback. STACK_TEST=1 rehearses the whole thing under stack name thermograph-test on throwaway volumes and ports 18137/18080.
• deploy/deploy-dev.sh — thin LAN-dev wrapper (dev compose overlay, ~/thermograph-dev). Its CI trigger is inert; see root CLAUDE.md.
• Makefile — compose orchestration only: up, down, db-up, dev-up, om-up, om-backfill.

Volumes are the reason the compose project name is pinned: compose creates thermograph_pgdata/_appdata/_applogs, and the Swarm stack declares those same names as external: true at the same mount paths.

Rules

• Never run terraform apply casually. No tfstate is persisted anywhere, so an apply would attempt full re-provisioning of live hosts. Terraform here is executable documentation until state is bootstrapped.
• Secrets: SOPS vault only (deploy/secrets/*.yaml, sops edit → commit → deploy). Never hand-edit /etc/thermograph.env — it is a rendered artifact. secrets-guard CI rejects plaintext. deploy/secrets/seed-from-live.sh reads production secrets and is not for an agent to run.
• The ops cron (.forgejo/workflows/ops-cron.yml, at the repo root) is THE prod backup. It uses PROD_SSH_*, not SSH_* — an earlier revision reused SSH_* and silently dumped beta while prod had no backup at all. If you touch it, verify a dump actually lands in agent@prod:~/thermograph-backups/.
• Shell here runs as root over SSH against live hosts with no test suite in front of it. shell-lint CI (pinned shellcheck) is the only guard — keep the tree at zero findings.

Commits & PRs

Concise and technical. Never mention AI, assistants or automated authorship.