From 418834c960c6a28c1e32d522131e78635e1b344e Mon Sep 17 00:00:00 2001
From: rob thijssen <grenade@rob.tn>
Date: Sun, 3 May 2026 18:07:57 +0300
Subject: [PATCH] docs(asset/sql): document mtls and ssh-sudo run modes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous bootstrap docs implied a `-U postgres` connection that
won't work over the network — postgres peer auth is local-socket
only. Document the two paths that actually work on this infra:

  (a) mTLS as the network superuser `grenade` using the host cert
      via PGSSL* env vars (cert paths from /etc/pki/tls per §11).
  (b) ssh to the db host and sudo to the local postgres peer.

No script changes — only comments in bootstrap.sql and
bootstrap-moments.sql.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 asset/sql/bootstrap-moments.sql | 16 ++++++++++++++--
 asset/sql/bootstrap.sql         | 20 ++++++++++++++++++--
 2 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/asset/sql/bootstrap-moments.sql b/asset/sql/bootstrap-moments.sql
index 6da8209..7210bd0 100644
--- a/asset/sql/bootstrap-moments.sql
+++ b/asset/sql/bootstrap-moments.sql
@@ -2,8 +2,20 @@
 -- Run after asset/sql/bootstrap.sql, against the moments database.
 -- Idempotent — safe to re-run on every deploy.
 --
---   psql -h magrathea.kosherinata.internal -U postgres -d moments \
---        -f asset/sql/bootstrap-moments.sql
+-- (a) mTLS as `grenade`:
+--
+--       PGSSLMODE=verify-full \
+--       PGSSLCERT=/etc/pki/tls/misc/$(hostname -f).pem \
+--       PGSSLKEY=/etc/pki/tls/private/$(hostname -f).pem \
+--       PGSSLROOTCERT=/etc/pki/ca-trust/source/anchors/root-internal.pem \
+--       psql -h magrathea.kosherinata.internal -U grenade -d moments \
+--            -f asset/sql/bootstrap-moments.sql
+--
+-- (b) ssh + sudo to the local postgres peer:
+--
+--       ssh magrathea.kosherinata.internal \
+--           sudo --user postgres psql -d moments -f - \
+--         < asset/sql/bootstrap-moments.sql
 --
 -- The schema itself is created by sqlx migrations executed by moments-api
 -- on startup (which runs as moments_rw, the database owner). This file
diff --git a/asset/sql/bootstrap.sql b/asset/sql/bootstrap.sql
index 98dda3d..e173d4f 100644
--- a/asset/sql/bootstrap.sql
+++ b/asset/sql/bootstrap.sql
@@ -2,8 +2,24 @@
 -- Run as a postgres superuser against the cluster's `postgres` database.
 -- Idempotent — safe to re-run on every deploy.
 --
---   psql -h magrathea.kosherinata.internal -U postgres -d postgres \
---        -f asset/sql/bootstrap.sql
+-- Two run modes — pick whichever fits your operator path:
+--
+-- (a) mTLS as the network superuser `grenade` (already mapped via pg_ident
+--     on magrathea + frankie). The host cert is picked up from the standard
+--     /etc/pki/tls paths via the PG* env vars:
+--
+--       PGSSLMODE=verify-full \
+--       PGSSLCERT=/etc/pki/tls/misc/$(hostname -f).pem \
+--       PGSSLKEY=/etc/pki/tls/private/$(hostname -f).pem \
+--       PGSSLROOTCERT=/etc/pki/ca-trust/source/anchors/root-internal.pem \
+--       psql -h magrathea.kosherinata.internal -U grenade -d postgres \
+--            -f asset/sql/bootstrap.sql
+--
+-- (b) ssh to the db host and run as the local `postgres` peer:
+--
+--       ssh magrathea.kosherinata.internal \
+--           sudo --user postgres psql -d postgres -f - \
+--         < asset/sql/bootstrap.sql
 --
 -- After this completes, run asset/sql/bootstrap-moments.sql against the
 -- newly created `moments` database to apply the in-database grants.