Jinemi/thermograph
4
0
Fork 0
Code Issues 2 Pull requests 10 Projects Releases Packages Wiki Activity Actions 1
thermograph/infra/ops/ICEBERG-HANDOFF.md
Emi Griffith 4e97d8e5dc
All checks were successful
PR build (required check) / changes (pull_request) Successful in 6s
Details
secrets-guard / encrypted (pull_request) Successful in 5s
Details
PR build (required check) / build-backend (pull_request) Has been skipped
Details
shell-lint / shellcheck (pull_request) Successful in 7s
Details
PR build (required check) / build-frontend (pull_request) Has been skipped
Details
PR build (required check) / validate-observability (pull_request) Successful in 18s
Details
PR build (required check) / gate (pull_request) Successful in 2s
Details
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 15:01:29 -07:00

8.8 KiB
Raw Blame History

Iceberg: implementing the agent-queryable service

Handoff spec for whoever builds the Iceberg layer. The Postgres equivalent is already shipped (infra/ops/dbq.sh) — mirror it. This document is the contract, the environment facts you'll trip over, and how the result gets verified.

Historical note: infra/ops/iceberg.sh now exists, originally built against the environment facts below as they stood before the vps1/vps2 split — beta at 75.119.132.91 and prod at 169.58.46.181, each its own box. iceberg.sh (and dbq.sh) have since been updated to resolve their SSH target and host facts from deploy/env-topology.sh instead of a hardcoded table, so they already reflect the current split (vps1 = 75.119.132.91 = dev + Forgejo + Grafana; vps2 = 169.58.46.181 = prod AND beta). This document is left as a historical record of the original design contract, not a live description of where each environment's engine runs — see infra/ops/README.md for the current behavior.

Definition of done

infra/ops/iceberg.sh exists and behaves like dbq.sh:

infra/ops/iceberg.sh prod -c "select count(*) from <namespace>.<table>"
infra/ops/iceberg.sh dev  -c "show tables"
echo "select 1" | infra/ops/iceberg.sh beta -f -

An agent (or operator) can query Iceberg in any environment, read-only, with no new network exposure and no interactive steps.

The contract (non-negotiable)

  1. Same interface shape as dbq.sh — iceberg.sh <dev|beta|prod> [flags] "<sql>". Extra flags pass through to the engine; stdin is forwarded so -f - works. Non-interactive, deterministic, safe to call from CI.
  2. Read-only enforced by the system, not by convention. A dedicated read-only identity — not an admin/superuser credential. You must be able to demonstrate a refused write (see Acceptance).
  3. No new network endpoints. Run the engine where the data is already reachable (containerised), rather than publishing ports or opening firewall rules. See the prod constraint below — this is not negotiable, it's physics.
  4. Env-keyed dispatch, names resolved at call time. Prod is Docker Swarm; task container names change on every redeploy. Resolve via docker ps --filter name=…; never hardcode a container name.
  5. No secrets in the repo or in workflow files.

Environment facts you need

As originally written (pre vps1/vps2 split; kept for history — see the note at the top of this document):

  • Monorepo emi/thermograph (domain dirs: backend/ frontend/ infra/ observability/). Ops tooling lives in infra/ops/.
  • Environments: dev = LAN compose stack on the dev machine; beta = 75.119.132.91; prod = 169.58.46.181. SSH as agent with ~/.ssh/thermograph_agent_ed25519 (passwordless sudo on both boxes).
  • Prod runs Docker Swarm. Its app database sits on the overlay network thermograph_internal (10.0.2.0/24), which the prod host itself cannot route to. Consequence, learned the hard way: ssh -L tunnelling works for beta but is impossible for prod. Any design that depends on a tunnel or a published port will fail on prod — that's why dbq.sh execs into the container instead. Assume the same for anything you deploy there.
  • The overlay is attachable=true, and the dev machine is a Swarm worker in the prod cluster (NodeAddr 10.10.0.3) — so docker run --network thermograph_internal … from the dev box is a plausible route to prod-side services. Untested; verify before relying on it.
  • WireGuard mesh: prod 10.10.0.1, beta 10.10.0.2, dev 10.10.0.3.
  • rclone and age are already installed on prod and beta.

Current facts, post vps1/vps2 split (the boxes and mesh IPs above did not move — only which environment runs where, and what the boxes are called):

  • vps2 = 169.58.46.181 = mesh 10.10.0.1 = the box called "prod" above. Runs both prod and beta now, as two separate Docker Swarm stacks — beta is a Swarm service too today, not a compose exception, so the tunnelling constraint above applies equally to it: ssh -L is impossible for beta now as well, not just prod.
  • vps1 = 75.119.132.91 = mesh 10.10.0.2 = the box called "beta" above. Runs Forgejo, Grafana/Loki/Alloy, and dev (its own Postgres container, reached over SSH like any fleet host — not the LAN-box-local case the original facts describe).
  • desktop = mesh 10.10.0.3 = "the dev machine" above. Hosts no Thermograph environment any more; it's a Swarm worker for flex capacity and AI-model hosting. The "dev machine is a Swarm worker in the prod cluster" fact still holds structurally (the desktop is still a worker node), but nothing about Iceberg or the app database routes through it any more.
  • Reference implementation to copy: infra/ops/dbq.sh + infra/ops/README.md.

Storage — almost certainly your warehouse

Contabo Object Storage (S3-compatible), already provisioned and in use:

  • Endpoint https://eu2.contabostorage.com · bucket era5-thermograph · region default · ~2 TB · private (keep it that way).
  • ⚠️ Contabo requires PATH-STYLE addressing. Set force_path_style=true / s3.path-style-access=true (whatever your engine's FileIO calls it) and region=default. Virtual-host-style addressing fails. This is validated, not theoretical.
  • ⚠️ The backups/ prefix is in use by the nightly backup jobs (prod DB + Forgejo). Put Iceberg data under its own prefix (e.g. iceberg/ or warehouse/). Do not write outside your prefix.
  • Credentials already exist — reuse them, don't mint new ones silently:
    • SOPS vault: infra/deploy/secrets/{prod,beta}.yaml as THERMOGRAPH_S3_* (rendered to /etc/thermograph.env at deploy by infra/deploy/render-secrets.sh).
    • Forgejo Actions secrets: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY.
    • If read-only S3 keys are needed for the query identity, ask the operator to mint a scoped keypair rather than reusing the read-write one.

Secrets handling

  • Host-side: SOPS + age. Recipient age1xx4dzs0dxlwvkv9sjuqzsphl7lfrxannkfken374yu2qvvcte9sqzktqt2; the private key is on each host at /etc/thermograph/age.key and on the operator's machine at ~/.config/sops/age/keys.txt.
  • CI-side: Forgejo Actions secrets.
  • ⚠️ beta gotcha: /etc/thermograph.env on beta is agent:agent 0640 — the deploy user cannot read it. If your service or job runs as deploy on beta, pull credentials from Actions secrets instead, or change the ownership deliberately and say so.

Decisions you must make — and report back

  1. Catalog: REST (Lakekeeper / Nessie / Polaris), JDBC-on-Postgres, Hive, or filesystem/hadoop — and where it runs per environment.
  2. Engine: DuckDB + iceberg extension, Trino, Spark, or pyiceberg. Prefer the lightest that satisfies the contract; it must run containerised and headless.
  3. Warehouse location: bucket + prefix, and whether environments are isolated by separate prefixes, namespaces, or buckets.
  4. Read-only mechanism: scoped S3 keys? catalog RBAC? engine restricted mode? State which, and how a write is refused.
  5. Where the engine runs for each env (local container on dev, on the box for beta/prod, or attached to the overlay) — consistent with constraint #3.

Acceptance criteria

The work is accepted when all of these are demonstrated with pasted output:

  • infra/ops/iceberg.sh <env> -c "<select>" returns rows for each environment that has data (explicitly state any env that doesn't yet).
  • A write/DDL attempt is refused by the system, with the error pasted. The Postgres bar to match: create table on prod → ERROR: permission denied for schema public.
  • No new exposure: sudo ss -ltnp on prod and beta shows no new listening port; no new ufw rules; no Swarm EndpointSpec publish added. State this explicitly.
  • Non-interactive: extra flags pass through, stdin (-f -) works.
  • Prod container/task resolution is dynamic (survives a redeploy).
  • infra/ops/README.md updated with an Iceberg section: usage examples and the why (same style as the Postgres rationale).

Anti-goals

  • ❌ Publishing catalog/engine/DB ports publicly, or adding firewall holes.
  • ❌ Any design requiring a persistent SSH tunnel (prod cannot be tunnelled).
  • ❌ Querying with an admin/superuser/read-write credential.
  • ❌ Secrets committed to the repo or pasted into workflow files.
  • ❌ Writing outside your own S3 prefix (backups/ is live and load-bearing).

Questions to route back to the operator

Anything that would require: minting new cloud credentials, opening a port, changing firewall/Swarm configuration, or writing to a shared prefix. Don't improvise on those — ask.