Files
faunosteo/scripts/db-trial.sh
T
bchanot b85614aa09 feat(supabase): db:trial backup, restore, destroy, migrate, rotations
Cold read-only backups proven before any change (checksums covering
the folder, entry counts, keys, images); typed confirmations at a
terminal only; rotate-secrets in one explicit transaction with a commit
marker, no secrets.prev; destroy refuses without a restorable backup and
names the manual way out. Harness: 210 stub-only cases.
2026-11-10 19:08:33 +01:00

1596 lines
76 KiB
Bash
Executable File

#!/usr/bin/env bash
# Dedicated persistent manual trial stack (docs/development/TRIAL_STACK.md, SUPABASE.md §5.2):
# Postgres, GoTrue, PostgREST, Storage, Mailpit and a gateway under the literal names
# faunosteo_trial_*, published on 127.0.0.1 only, the data in two named volumes, secrets of its
# own. Nothing starts at boot. No automated suite reaches it: this script refuses a shell that
# carries SANDBOX_* variables, and the suites accept the sandbox's exact values only.
#
# pnpm db:trial plan read-only: what create would make, ports, places, limits, refusals
# pnpm db:trial create secrets, network, volumes, services, migrations, equine_draft.sql only
# pnpm db:trial start | stop the same containers, data kept
# pnpm db:trial status read-only: containers, keys, migrations, equine sheet, accounts, backups
# pnpm db:trial migrate a backup first (A15), then the branch's new migrations
# pnpm db:trial backup cold copy of both volumes and the secrets (the stack stops a few seconds)
# pnpm db:trial restore <backup> typed confirmation, a backup first, then <backup>'s volumes and secrets
# pnpm db:trial rotate-keys new anon and service keys signed with the same JWT secret, one year
# pnpm db:trial rotate-secrets a backup first, then a new JWT secret, keys and role passwords
# pnpm db:trial app the app on http://<trial host>:5194; Ctrl+C stops it, the stack stays
# pnpm db:trial account <email> a confirmed account, password at a hidden prompt (12 characters min.)
# pnpm db:trial grant <email> <owner|admin|catalog_reader|sheet_editor|sheet_reviewer|sheet_publisher>
# pnpm db:trial assets the equine drawings through the trial gateway, then checked
# pnpm db:trial destroy inventory, typed confirmation, a backup, then containers, network, volumes
#
# State: $FAUNOSTEO_TRIAL_DIR (default ~/.cache/faunosteo-trial), 700, outside every git work tree:
# secrets.env and the services' env files (600, written whole then renamed), stack.conf (images),
# migrations.sha256, backups/ (never pruned here). No secret is printed, logged, written to the
# repository or put on a command line: containers read env files, tools their environment, psql its
# standard input. Never `docker inspect` a trial container without -f: it would print the env files.
# Typed confirmations need a terminal. Every command but plan needs a reachable Docker daemon.
set -euo pipefail
cd "$(dirname "$0")/.."
# shellcheck source=scripts/dev-env.sh
. scripts/dev-env.sh
# Pinned here, apart from the sandbox: an image change on this persistent stack is a deliberate
# step. create records the images in stack.conf; every later recreation reuses the recorded ones.
IMAGE_DB=public.ecr.aws/supabase/postgres:17.11.0.004
IMAGE_AUTH=public.ecr.aws/supabase/gotrue:v2.197.0
IMAGE_REST=public.ecr.aws/supabase/postgrest:v16.4
IMAGE_STORAGE=public.ecr.aws/supabase/storage-api:v1.79.36
IMAGE_MAIL=public.ecr.aws/supabase/mailpit:v1.31.3
IMAGE_GATEWAY=nginx:1.31-alpine
NET=faunosteo_trial_net
DB=faunosteo_trial_db
MAIL=faunosteo_trial_mail
AUTH=faunosteo_trial_auth
STORAGE=faunosteo_trial_storage
REST=faunosteo_trial_rest
GATEWAY=faunosteo_trial_gateway
HELPER=faunosteo_trial_helper
VOL_DB=faunosteo_trial_db
VOL_STORAGE=faunosteo_trial_storage
CONTAINERS=("$DB" "$MAIL" "$AUTH" "$STORAGE" "$REST" "$GATEWAY")
STOP_ORDER=("$GATEWAY" "$REST" "$STORAGE" "$AUTH" "$MAIL" "$DB")
PORT_DB=58432 PORT_AUTH=58999 PORT_REST=58300 PORT_STORAGE=58500 PORT_MAIL=58025 PORT_GATEWAY=58801
PORT_APP=5194
# The six caps add up to 1 920 MiB (TRIAL_STACK.md §3.7); about 650 MiB are used in practice.
MEMORY_FLOOR_MIB=2048
SEED=supabase/seed/anatomical-sheets/equine/draft
HISTORICAL_SHEET=503dc301-a8b1-50d4-9e44-0919b2fc2916
CLI=node_modules/.bin/supabase
# Canonical from the start (symlinks resolved): the guard, every mode check and every state path
# below read the real folder, never a link (whose own mode stat would report as 777).
STATE="$(realpath -m "${FAUNOSTEO_TRIAL_DIR:-$HOME/.cache/faunosteo-trial}")"
MARKER="$STATE/.faunosteo-trial-state"
SECRETS="$STATE/secrets.env"
CONF="$STATE/stack.conf"
MANIFEST="$STATE/migrations.sha256"
BACKUPS="$STATE/backups"
# Everything in the state folder but the marker, the lock and backups/: what destroy (and a create
# that died before its first resource) removes.
LIVE_FILES=(secrets.env secrets.next.env db.env auth.env storage.env rest.env stack.conf migrations.sha256)
JWT_RE='^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$'
die() { echo "db-trial: $*" >&2; exit 1; }
say() { echo "== $*"; }
usage() { grep '^# pnpm db:trial' "$0" | cut -c2-; }
# Any git work tree, not only this one (the other checkout, a dotfiles repository): the secrets
# and backups would sit one `git add` away from a commit. Fails closed: a `.git` entry (folder or
# file) in any ancestor refuses; then git itself answers with its own repository variables unset,
# and only "not a git repository" counts as outside.
refuse_inside_git() { # canonical state path
local dir="$1" status=0 answer
local why="FAUNOSTEO_TRIAL_DIR must be outside every git work tree: refused"
while :; do
[ ! -e "$dir/.git" ] || die "$why"
[ "$dir" != / ] || break
dir="$(dirname "$dir")"
done
dir="$1"
while [ ! -e "$dir" ]; do dir="$(dirname "$dir")"; done
answer="$( (unset GIT_DIR GIT_WORK_TREE GIT_CEILING_DIRECTORIES; git -C "$dir" rev-parse --is-inside-work-tree) 2>&1)" || status=$?
case "$status" in
0) [ "$answer" != true ] || die "$why"
die "git answered '$answer' for $dir: cannot tell whether it is a work tree, refused" ;;
128) case "$answer" in
*"not a git repository"*) ;;
*) die "git failed for $dir ($answer): cannot tell whether it is a work tree, refused" ;;
esac ;;
*) die "git failed for $dir (exit $status): cannot tell whether it is a work tree, refused" ;;
esac
}
# Refusals that come before anything else, whatever the command (TRIAL_STACK.md §3.6).
guard_environment() {
local name repo state sandbox
for name in $(compgen -e); do
case "$name" in
SANDBOX_*) die "$name is set: this shell is wired to the sandbox suites; open a clean shell (nothing was run)" ;;
esac
done
repo="$(realpath "$PWD")"
state="$STATE"
sandbox="$(realpath -m "${FAUNOSTEO_SANDBOX_DIR:-$HOME/.cache/faunosteo-db-sandbox}")"
case "$state" in
"$repo" | "$repo"/*) die "FAUNOSTEO_TRIAL_DIR must be outside the repository" ;;
esac
refuse_inside_git "$state"
[ "$state" != "$sandbox" ] || die "FAUNOSTEO_TRIAL_DIR is the sandbox's state folder: refused"
if [ -e "$STATE" ] && [ ! -e "$MARKER" ] && [ -n "$(ls -A "$STATE" 2>/dev/null || echo unreadable)" ]; then
die "$STATE is not empty and holds no db:trial state: refused"
fi
}
check_private() { # path mode
[ "$(stat -c %u "$1")" = "$(id -u)" ] && [ "$(stat -c %a "$1")" = "$2" ] \
|| die "$1 must belong to $(id -un) with mode $2: refused"
}
# KEY=value lines, read without `source`: only these keys, each value checked against its shape.
parse_secrets() { # file → TR_PW TR_JWT_SECRET TR_ANON_KEY TR_SERVICE_KEY
local key value
TR_PW='' TR_JWT_SECRET='' TR_ANON_KEY='' TR_SERVICE_KEY=''
while IFS='=' read -r key value; do
case "$key" in
TR_PW) if [[ "$value" =~ ^[0-9a-f]{48}$ ]]; then TR_PW="$value"; fi ;;
TR_JWT_SECRET) if [[ "$value" =~ ^[0-9a-f]{64}$ ]]; then TR_JWT_SECRET="$value"; fi ;;
TR_ANON_KEY) if [[ "$value" =~ $JWT_RE ]]; then TR_ANON_KEY="$value"; fi ;;
TR_SERVICE_KEY) if [[ "$value" =~ $JWT_RE ]]; then TR_SERVICE_KEY="$value"; fi ;;
esac
done < "$1"
[ -n "$TR_PW" ] && [ -n "$TR_JWT_SECRET" ] && [ -n "$TR_ANON_KEY" ] && [ -n "$TR_SERVICE_KEY" ]
}
load_secrets() {
[ -f "$SECRETS" ] || die "not created: no $SECRETS (pnpm db:trial plan, then create)"
check_private "$SECRETS" 600
parse_secrets "$SECRETS" || die "secrets.env is incomplete or malformed: nothing was run (pnpm db:trial restore <backup>)"
}
# A state file is written whole under <file>.new (600) then renamed: an interrupted write never
# leaves half a file behind the real name. Content on stdin (printf is a builtin: no argv).
write_private() { # file
( umask 077; cat > "$1.new" ) && mv -f "$1.new" "$1"
}
remove_live_files() { # never backups/, the marker or the lock
local f
for f in "${LIVE_FILES[@]}"; do rm -f -- "$STATE/$f" "$STATE/$f.new"; done
}
# The six IMAGE_* recorded at create. The app host is not recorded: `app` decides it at each run.
parse_conf() { # file
local key value seen=0
while IFS='=' read -r key value; do
case "$key" in
IMAGE_DB | IMAGE_AUTH | IMAGE_REST | IMAGE_STORAGE | IMAGE_MAIL | IMAGE_GATEWAY)
if [[ "$value" =~ ^[a-z0-9./_-]+:[A-Za-z0-9._-]+$ ]]; then printf -v "$key" '%s' "$value"; seen=$((seen + 1)); fi ;;
esac
done < "$1"
[ "$seen" -eq 6 ]
}
load_conf() {
[ -f "$CONF" ] || die "not created: no $CONF (pnpm db:trial plan, then create)"
check_private "$CONF" 600
parse_conf "$CONF" || die "stack.conf is incomplete or malformed: nothing was run (pnpm db:trial restore <backup>)"
}
write_conf() {
printf 'IMAGE_DB=%s\nIMAGE_AUTH=%s\nIMAGE_REST=%s\nIMAGE_STORAGE=%s\nIMAGE_MAIL=%s\nIMAGE_GATEWAY=%s\n' \
"$IMAGE_DB" "$IMAGE_AUTH" "$IMAGE_REST" "$IMAGE_STORAGE" "$IMAGE_MAIL" "$IMAGE_GATEWAY" | write_private "$CONF"
}
# Fresh values (`new`) or new keys for the current secret (`keys`, the secret in TR_JWT_SECRET),
# as KEY=value lines for a 600 file, never for the terminal. Keys: issuer faunosteo-trial (the
# sandbox suites refuse it), one year, a random jti so every rotation yields new keys.
KEYGEN='
const c = require("crypto");
const fresh = process.argv[1] === "new";
const secret = fresh ? c.randomBytes(32).toString("hex") : process.env.TR_JWT_SECRET;
if (!/^[0-9a-f]{64}$/.test(secret || "")) process.exit(2);
const b64 = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
const jwt = (p) => { const h = b64({ alg: "HS256", typ: "JWT" }), b = b64(p);
return h + "." + b + "." + c.createHmac("sha256", secret).update(h + "." + b).digest("base64url"); };
const iat = Math.floor(Date.now() / 1000), exp = iat + 365 * 86400;
if (fresh) console.log("TR_PW=" + c.randomBytes(24).toString("hex") + "\nTR_JWT_SECRET=" + secret);
for (const [name, role] of [["TR_ANON_KEY", "anon"], ["TR_SERVICE_KEY", "service_role"]])
console.log(name + "=" + jwt({ role, iss: "faunosteo-trial", iat, exp, jti: c.randomUUID() }));
'
new_secrets_file() { # file: written whole under <file>.new (600), then renamed
if ( umask 077; node -e "$KEYGEN" new > "$1.new" ) && mv -f "$1.new" "$1"; then return 0; fi
rm -f -- "$1.new"
return 1
}
# A key is handed over (Vite, the upload tool, GoTrue's admin API, Storage's env) only when it is
# this stack's: issuer faunosteo-trial, the role asked, not expired, signed with TR_JWT_SECRET.
# Exit 0: this stack's key; 1: not this stack's (issuer, role, signature); 3 (mode fresh only):
# this stack's but expired. Identity and expiry are apart on purpose: an expired key must never
# block start or rotate-keys (the way to renew it), only its use by a client.
KEYCHECK='
const c = require("crypto");
const [role, mode] = process.argv.slice(1);
const [h, b, s] = (process.env.KEY || "").split(".");
let p = null;
try { p = JSON.parse(Buffer.from(b, "base64url").toString("utf8")); } catch { process.exit(1); }
const mac = c.createHmac("sha256", process.env.SECRET || "").update(h + "." + b).digest("base64url");
const own = p !== null && typeof p === "object" && s === mac && p.iss === "faunosteo-trial"
&& p.role === role && typeof p.exp === "number";
if (!own) process.exit(1);
process.exit(mode === "fresh" && p.exp <= Date.now() / 1000 ? 3 : 0);
'
key_check() { # key role any|fresh [secret]: the status of KEYCHECK
KEY="$1" SECRET="${4:-$TR_JWT_SECRET}" node -e "$KEYCHECK" "$2" "$3"
}
key_identity() { # key role: this stack's key, expired or not (env files, Storage)
key_check "$1" "$2" any \
|| die "the $2 key in secrets.env is not this stack's (issuer faunosteo-trial, signed with its secret): refused, nothing was done (pnpm db:trial restore <backup>)"
}
client_key() { # key role: what a client receives (Vite, the upload tool, GoTrue's admin API) is also valid now
local status=0
key_check "$1" "$2" fresh || status=$?
case "$status" in
0) ;;
3) die "the $2 key expired: pnpm db:trial rotate-keys renews it; nothing was done" ;;
*) die "the $2 key in secrets.env is not this stack's (issuer faunosteo-trial, signed with its secret): refused, nothing was done (pnpm db:trial restore <backup>)" ;;
esac
}
require_trial_keys() {
key_identity "$TR_ANON_KEY" anon
key_identity "$TR_SERVICE_KEY" service_role
}
key_expiry() {
TR_ANON_KEY="$TR_ANON_KEY" node -e '
const p = JSON.parse(Buffer.from(process.env.TR_ANON_KEY.split(".")[1], "base64url"));
console.log(new Date(p.exp * 1000).toISOString().slice(0, 10));'
}
# The values reach the containers through 600 env files, never through argv. Always derived from
# secrets.env, so they can be rewritten at any time (start rewrites them before recreating a
# missing container). Both keys are this stack's first.
write_env_files() {
require_trial_keys
printf 'POSTGRES_PASSWORD=%s\nPGPASSWORD=%s\nJWT_SECRET=%s\n' "$TR_PW" "$TR_PW" "$TR_JWT_SECRET" \
| write_private "$STATE/db.env"
printf 'GOTRUE_DB_DATABASE_URL=postgresql://supabase_auth_admin:%s@%s:5432/postgres\nGOTRUE_JWT_SECRET=%s\n' \
"$TR_PW" "$DB" "$TR_JWT_SECRET" | write_private "$STATE/auth.env"
printf 'ANON_KEY=%s\nSERVICE_KEY=%s\nAUTH_JWT_SECRET=%s\nDATABASE_URL=postgresql://supabase_storage_admin:%s@%s:5432/postgres\n' \
"$TR_ANON_KEY" "$TR_SERVICE_KEY" "$TR_JWT_SECRET" "$TR_PW" "$DB" | write_private "$STATE/storage.env"
printf 'PGRST_DB_URI=postgresql://authenticator:%s@%s:5432/postgres\nPGRST_JWT_SECRET=%s\n' \
"$TR_PW" "$DB" "$TR_JWT_SECRET" | write_private "$STATE/rest.env"
}
# The daemon this script talks to is the local one: DOCKER_HOST unset or a unix socket, else the
# current context's endpoint a unix socket (a named, non-secret field of the context).
daemon_endpoint() {
if [ -n "${DOCKER_HOST:-}" ]; then printf '%s' "$DOCKER_HOST"
else docker context inspect -f '{{.Endpoints.docker.Host}}' 2>/dev/null; fi
}
require_local_daemon() {
local endpoint
endpoint="$(daemon_endpoint)" || die "the current Docker context cannot be read: refused, nothing was run"
case "$endpoint" in
unix://?*) ;;
*) die "the Docker endpoint '${endpoint##*@}' is not a local unix socket (DOCKER_HOST or the current context): refused, nothing was run" ;;
esac
}
# Checked at dispatch for every command but plan: past it, "absent" means absent, not "daemon down".
daemon_ok() { docker info --format '{{.ServerVersion}}' >/dev/null 2>&1; }
# Always -f with a named field: a bare inspect prints the containers' env-file values.
# "No such <kind>" is the only answer read as absent; any other inspect error refuses.
resource_exists() { # kind name: 0 exists, 1 absent, else die
local out status=0
out="$(docker "$1" inspect -f '{{.Name}}' "$2" 2>&1)" || status=$?
[ "$status" -ne 0 ] || return 0
# Docker's wordings differ by kind: "No such container: x", "get x: no such volume", "network x not found".
case "${out,,}" in *"no such"* | *"not found"*) return 1 ;; esac
die "docker $1 inspect $2 failed (exit $status) with an answer other than 'no such' / 'not found': refused, nothing was changed"
}
container_exists() { resource_exists container "$1"; }
container_running() { [ "$(docker container inspect -f '{{.State.Running}}' "$1" 2>/dev/null)" = true ]; }
volume_exists() { resource_exists volume "$1"; }
network_exists() { resource_exists network "$1"; }
existing_resources() { # the literal names of this stack that exist now, one per line
local name
for name in "${CONTAINERS[@]}"; do if container_exists "$name"; then echo "container $name"; fi; done
if network_exists "$NET"; then echo "network $NET"; fi
for name in "$VOL_DB" "$VOL_STORAGE"; do if volume_exists "$name"; then echo "volume $name"; fi; done
}
port_of() { # name → host port, container port
case "$1" in
"$DB") echo "$PORT_DB 5432" ;; "$MAIL") echo "$PORT_MAIL 8025" ;; "$AUTH") echo "$PORT_AUTH 9999" ;;
"$STORAGE") echo "$PORT_STORAGE 5000" ;; "$REST") echo "$PORT_REST 3000" ;; "$GATEWAY") echo "$PORT_GATEWAY 8000" ;;
esac
}
limits_of() { # name → memory, pids (TRIAL_STACK.md §3.7; --cpus 1 for all)
case "$1" in
"$DB") echo "1g 512" ;; "$REST") echo "384m 256" ;; "$STORAGE") echo "256m 256" ;;
"$AUTH") echo "128m 256" ;; "$MAIL" | "$GATEWAY") echo "64m 64" ;;
esac
}
image_of() {
case "$1" in
"$DB") echo "$IMAGE_DB" ;; "$MAIL") echo "$IMAGE_MAIL" ;; "$AUTH") echo "$IMAGE_AUTH" ;;
"$STORAGE") echo "$IMAGE_STORAGE" ;; "$REST") echo "$IMAGE_REST" ;; "$GATEWAY") echo "$IMAGE_GATEWAY" ;;
esac
}
mount_of() {
case "$1" in
"$DB") echo "$VOL_DB:/var/lib/postgresql/data" ;; "$STORAGE") echo "$VOL_STORAGE:/mnt" ;; *) echo - ;;
esac
}
# What every service container shares: its name, the stack network, no restart at boot, its caps
# and its one loopback port.
base_opts() { # name → one option per line
local host inner memory pids
read -r host inner <<<"$(port_of "$1")"
read -r memory pids <<<"$(limits_of "$1")"
printf '%s\n' --name "$1" --network "$NET" --restart no --memory "$memory" --cpus 1 \
--pids-limit "$pids" -p "127.0.0.1:$host:$inner"
}
# True when any local address listens on the port (rootless Docker's forwarders show in ss too,
# checked 2026-11-10). Fails closed: no ss answer, no command goes on.
port_listening() { # port
local out status=0
out="$(ss -Hltn "sport = :$1" 2>&1)" || status=$?
# Fail closed: an ss error is never read as "nothing listens".
[ "$status" -eq 0 ] || die "ss cannot list the listening ports (exit $status): nothing was done"
[ -n "$out" ]
}
ports_free() { # container...: each one's host port, all checked before any docker call
local name host inner
for name in "$@"; do
read -r host inner <<<"$(port_of "$name")"
if port_listening "$host"; then die "port 127.0.0.1:$host is taken: nothing was started or changed (pnpm db:trial plan)"; fi
done
}
available_mib() { awk '/^MemAvailable:/ { print int($2 / 1024) }' /proc/meminfo; }
memory_ok() {
local mib
mib="$(available_mib)"
[ "$mib" -ge "$MEMORY_FLOOR_MIB" ] || die "only $mib MiB of memory available, the stack's caps need $MEMORY_FLOOR_MIB: nothing was started"
}
# The trial app host: loopback or a private IPv4 of an interface of this machine, nothing else
# (same rule as db-sandbox.sh trial_host). Prints the normalised address.
valid_host() { # address
local host="$1" a b c d
[[ "$host" =~ ^([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})\.([0-9]{1,3})$ ]] \
|| die "FAUNOSTEO_TRIAL_HOST must be an IPv4 address (not a name, not 0.0.0.0): $host"
a=$((10#${BASH_REMATCH[1]})) b=$((10#${BASH_REMATCH[2]}))
c=$((10#${BASH_REMATCH[3]})) d=$((10#${BASH_REMATCH[4]}))
[ "$a" -le 255 ] && [ "$b" -le 255 ] && [ "$c" -le 255 ] && [ "$d" -le 255 ] \
|| die "FAUNOSTEO_TRIAL_HOST is not an IPv4 address: $host"
[ "$host" = "$a.$b.$c.$d" ] || die "FAUNOSTEO_TRIAL_HOST: write the address without leading zeros"
if [ "$a" -eq 127 ]; then host=127.0.0.1
elif [ "$a" -eq 10 ] || { [ "$a" -eq 172 ] && [ "$b" -ge 16 ] && [ "$b" -le 31 ]; } \
|| { [ "$a" -eq 192 ] && [ "$b" -eq 168 ]; }; then :
else die "FAUNOSTEO_TRIAL_HOST must be loopback or a private address (10/8, 172.16/12, 192.168/16): $host"
fi
ip -4 -o addr | grep -qF "inet $host/" || die "FAUNOSTEO_TRIAL_HOST $host is not an address of this machine"
printf '%s' "$host"
}
# Decided at each use, never recorded: a DHCP change of the LAN address needs no state edit. Call
# it as `host="$(trial_host)"` (a plain assignment, so a refusal stops the script).
trial_host() { valid_host "${FAUNOSTEO_TRIAL_HOST:-$FAUNOSTEO_DEV_HOST}"; }
wait_for() { # what command...
local what="$1"
shift
for _ in $(seq 1 120); do
if "$@" >/dev/null 2>&1; then return 0; fi
sleep 1
done
die "timeout waiting for $what"
}
# psql inside the database container; the password reaches it through the environment.
db_ready() { # role
PGPASSWORD="$TR_PW" docker exec -e PGPASSWORD "$DB" psql -X -h 127.0.0.1 -U "$1" -d postgres -c 'select 1'
}
sb_psql() {
PGPASSWORD="$TR_PW" docker exec -i -e PGPASSWORD "$DB" \
psql -X -q -h 127.0.0.1 -U postgres -d postgres -v ON_ERROR_STOP=1 "$@"
}
# The role passwords the CLI sets at its first database start (/etc/postgresql.schema.sql, run
# once on an empty data folder), for the roles this stack uses, supabase_admin included so that
# rotate-secrets can renew every password through it. A failing ALTER would log its statement,
# password included, at the default log_min_error_statement: the session turns that off first.
# shellcheck disable=SC2016
DB_INIT='cat <<'"'"'EOF'"'"' > /etc/postgresql.schema.sql && exec docker-entrypoint.sh postgres -D /etc/postgresql -c shared_buffers=128MB
set log_min_error_statement = panic;
\set pgpass `echo "$PGPASSWORD"`
\set jwt_secret `echo "$JWT_SECRET"`
ALTER DATABASE postgres SET "app.settings.jwt_secret" TO :'"'"'jwt_secret'"'"';
ALTER DATABASE postgres SET "app.settings.jwt_exp" TO '"'"'3600'"'"';
ALTER USER supabase_admin WITH PASSWORD :'"'"'pgpass'"'"';
ALTER USER postgres WITH PASSWORD :'"'"'pgpass'"'"';
ALTER USER authenticator WITH PASSWORD :'"'"'pgpass'"'"';
ALTER USER supabase_auth_admin WITH PASSWORD :'"'"'pgpass'"'"';
ALTER USER supabase_storage_admin WITH PASSWORD :'"'"'pgpass'"'"';
EOF'
# The CLI stack's Kong routes on the trial network. GoTrue's admin API is not routed: the account
# command calls GoTrue on its loopback port, so the app's LAN proxy never reaches it. The static
# /__faunosteo_stack answer names this gateway (R13: app, assets and the trial Vite config check
# it); it carries no data, and Vite proxies only the three Supabase routes, so the LAN never sees it.
GATEWAY_CONF='server {
listen 8000;
client_max_body_size 8m;
proxy_http_version 1.1;
location = /__faunosteo_stack { default_type text/plain; return 200 "faunosteo_trial\n"; }
location /auth/v1/admin/ { return 403; }
location /auth/v1/ { proxy_pass http://'"$AUTH"':9999/; }
location /rest/v1/ { proxy_pass http://'"$REST"':3000/; }
location /storage/v1/ { proxy_pass http://'"$STORAGE"':5000/; }
location / { return 404; }
}'
# Every curl of this script: -q first (no ~/.curlrc: no proxy, connect-to or resolve from it) and
# --noproxy '*' (no http_proxy / ALL_PROXY): the destination is the literal 127.0.0.1 port, always.
wait_service() { # name
case "$1" in
"$DB")
wait_for "database roles" db_ready supabase_auth_admin
wait_for "database" db_ready postgres ;;
"$MAIL") wait_for "mailpit" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_MAIL/" ;;
"$AUTH") wait_for "auth" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_AUTH/health" ;;
"$STORAGE") wait_for "storage" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_STORAGE/status" ;;
"$REST") wait_for "postgrest" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_REST/" ;;
"$GATEWAY") wait_for "gateway" curl -q --noproxy '*' -fsS -o /dev/null "http://127.0.0.1:$PORT_GATEWAY/rest/v1/" ;;
esac
}
run_db() {
local opts
mapfile -t opts < <(base_opts "$DB")
docker run -d "${opts[@]}" -v "$(mount_of "$DB")" --env-file "$STATE/db.env" \
-e POSTGRES_HOST=/var/run/postgresql -e JWT_EXP=3600 \
-e POSTGRES_INITDB_ARGS="--allow-group-access --locale-provider=icu --encoding=UTF-8 --icu-locale=en_US.UTF-8" \
--entrypoint sh "$IMAGE_DB" -c "$DB_INIT" >/dev/null
}
run_mail() {
local opts
mapfile -t opts < <(base_opts "$MAIL")
docker run -d "${opts[@]}" "$IMAGE_MAIL" >/dev/null
}
# Sign-up closed (accounts come from `account` only); mail links lead to the app origin of the
# trial host at the time GoTrue starts (create, restore, rotate-secrets, a recreation by start),
# whose proxy forwards /auth/v1 to GoTrue.
run_auth() {
local opts host origin
host="$(trial_host)"
origin="http://$host:$PORT_APP"
mapfile -t opts < <(base_opts "$AUTH")
docker run -d "${opts[@]}" --env-file "$STATE/auth.env" \
-e GOTRUE_API_HOST=0.0.0.0 -e GOTRUE_API_PORT=9999 -e API_EXTERNAL_URL="$origin/auth/v1" \
-e GOTRUE_DB_DRIVER=postgres -e GOTRUE_DB_MIGRATIONS_PATH=/usr/local/etc/auth/migrations \
-e GOTRUE_SITE_URL="$origin" -e GOTRUE_URI_ALLOW_LIST="$origin/**" -e GOTRUE_DISABLE_SIGNUP=true \
-e GOTRUE_JWT_EXP=3600 -e GOTRUE_JWT_AUD=authenticated -e GOTRUE_JWT_DEFAULT_GROUP_NAME=authenticated \
-e GOTRUE_JWT_ADMIN_ROLES=service_role \
-e GOTRUE_EXTERNAL_EMAIL_ENABLED=true -e GOTRUE_EXTERNAL_PHONE_ENABLED=false \
-e GOTRUE_EXTERNAL_ANONYMOUS_USERS_ENABLED=false -e GOTRUE_MAILER_AUTOCONFIRM=false \
-e GOTRUE_MAILER_URLPATHS_CONFIRMATION="$origin/auth/v1/verify" \
-e GOTRUE_SMTP_HOST="$MAIL" -e GOTRUE_SMTP_PORT=1025 \
-e GOTRUE_SMTP_ADMIN_EMAIL=admin@trial.local -e GOTRUE_SMTP_SENDER_NAME=faunosteo-trial \
-e GOTRUE_PASSWORD_MIN_LENGTH=12 "$IMAGE_AUTH" >/dev/null
}
run_storage() {
local opts
mapfile -t opts < <(base_opts "$STORAGE")
docker run -d "${opts[@]}" -v "$(mount_of "$STORAGE")" --env-file "$STATE/storage.env" \
-e FILE_SIZE_LIMIT=52428800 -e STORAGE_BACKEND=file -e FILE_STORAGE_BACKEND_PATH=/mnt \
-e TENANT_ID=stub -e STORAGE_S3_REGION=local -e GLOBAL_S3_BUCKET=stub \
-e ENABLE_IMAGE_TRANSFORMATION=false -e IMAGE_TRANSFORMATION_ENABLED=false \
-e S3_PROTOCOL_ENABLED=false -e DB_MIGRATIONS_FREEZE_AT= "$IMAGE_STORAGE" >/dev/null
}
run_rest() {
local opts
mapfile -t opts < <(base_opts "$REST")
docker run -d "${opts[@]}" --env-file "$STATE/rest.env" \
-e PGRST_DB_SCHEMAS=public -e PGRST_DB_EXTRA_SEARCH_PATH=public,extensions \
-e PGRST_DB_ANON_ROLE=anon -e PGRST_DB_MAX_ROWS=1000 "$IMAGE_REST" >/dev/null
}
run_gateway() {
local opts
mapfile -t opts < <(base_opts "$GATEWAY")
# "$0" is the inner shell's, expanded in the container:
# shellcheck disable=SC2016
docker run -d "${opts[@]}" --security-opt no-new-privileges:true \
--entrypoint sh "$IMAGE_GATEWAY" -c 'printf "%s\n" "$0" > /etc/nginx/conf.d/default.conf && exec nginx -g "daemon off;"' \
"$GATEWAY_CONF" >/dev/null
}
run_service() { # name: run, then wait until it answers
case "$1" in
"$DB") run_db ;; "$MAIL") run_mail ;; "$AUTH") run_auth ;;
"$STORAGE") run_storage ;; "$REST") run_rest ;; "$GATEWAY") run_gateway ;;
esac
wait_service "$1"
}
published_exactly() { # name: its one port, on 127.0.0.1, and nothing else
local host inner
read -r host inner <<<"$(port_of "$1")"
[ "$(docker port "$1" 2>/dev/null)" = "$inner/tcp -> 127.0.0.1:$host" ] \
|| die "$1 is not published on 127.0.0.1:$host only: refused (pnpm db:trial stop, then check Docker)"
}
check_loopback() {
local name
for name in "${CONTAINERS[@]}"; do published_exactly "$name"; done
}
# The gateway a tool or the app is pointed at is this stack's container, on its port, answering
# its name; never another local service on 58801.
STACK_IDENTITY=faunosteo_trial
gateway_identity() {
local body
published_exactly "$GATEWAY"
body="$(curl -q --noproxy '*' -fsS --max-time 3 "http://127.0.0.1:$PORT_GATEWAY/__faunosteo_stack" 2>/dev/null)" || body=''
[ "$body" = "$STACK_IDENTITY" ] \
|| die "127.0.0.1:$PORT_GATEWAY does not answer as the faunosteo_trial gateway: refused, nothing was done"
}
ensure_network() {
if ! network_exists "$NET"; then docker network create --label faunosteo.stack=trial "$NET" >/dev/null; fi
}
# nginx resolves the services' names once, at its start: a service started or recreated under a
# running gateway means a gateway restart.
restart_gateway() {
docker restart -t 10 "$GATEWAY" >/dev/null
wait_service "$GATEWAY"
}
# Every port of a stopped or missing container is checked before the first start. A missing
# container is recreated from stack.conf and secrets.env (env files rewritten first), so a failed
# recreation (rotate-keys, restore, a daemon hiccup) is repaired by `start`, never by a restore.
start_containers() {
local name todo=() missing=no
for name in "${CONTAINERS[@]}"; do
if container_running "$name"; then continue; fi
todo+=("$name")
if ! container_exists "$name"; then missing=yes; fi
done
ports_free "${todo[@]}"
if [ "$missing" = yes ]; then write_env_files; ensure_network; fi
for name in "${todo[@]}"; do
if container_exists "$name"; then
docker start "$name" >/dev/null
wait_service "$name"
else
run_service "$name"
fi
done
# CONTAINERS ends with the gateway: when it was not started last, it ran over the others.
if [ "${#todo[@]}" -gt 0 ] && [ "${todo[-1]}" != "$GATEWAY" ]; then restart_gateway; fi
check_loopback
}
stop_containers() {
local name
for name in "${STOP_ORDER[@]}"; do
if container_running "$name"; then docker stop -t 60 "$name" >/dev/null; fi
done
}
remove_containers() { # stopped first by the caller; volumes untouched
local name
for name in "${CONTAINERS[@]}"; do
if container_exists "$name"; then docker rm "$name" >/dev/null; fi
done
}
require_state() {
[ -e "$MARKER" ] || die "no db:trial state in $STATE (pnpm db:trial plan, then create)"
check_private "$STATE" 700
}
# The data volume is the stack: containers can be recreated (start), the volume cannot.
require_created() {
require_state
load_conf
load_secrets
volume_exists "$VOL_DB" || die "$VOL_DB does not exist (pnpm db:trial status)"
}
require_running() {
local name
require_created
for name in "${CONTAINERS[@]}"; do
container_running "$name" || die "$name is not running (pnpm db:trial start)"
done
}
# Before the commands that change keys or data under a running app (rotate-keys, rotate-secrets,
# restore, destroy) and before stop (the app would proxy to whatever then answers 58801). A local
# listener check: no probe of a LAN address.
refuse_while_app_runs() {
if port_listening "$PORT_APP"; then
die "port $PORT_APP is in use (the trial app, or another process): stop it first; nothing was changed"
fi
}
take_lock() {
local previous
previous="$(umask)"
umask 077
exec 9>"$STATE/.lock"
umask "$previous"
flock -n 9 || die "another pnpm db:trial command is running"
}
db_url() { printf 'postgresql://postgres@127.0.0.1:%s/postgres?sslmode=disable' "$PORT_DB"; }
# The CLI's own runner, always against the trial URL; the password through PGPASSWORD only.
migrate_up() { PGPASSWORD="$TR_PW" "$CLI" --workdir . migration up --db-url "$(db_url)"; }
applied_versions() {
sb_psql -t -A -c "-- db-trial:applied
select version from supabase_migrations.schema_migrations order by version"
}
file_version() { basename "$1" | cut -d_ -f1; }
file_sum() { sha256sum < "$1" | cut -d' ' -f1; }
# One line per applied migration: version, sha256 of its file, file name. A persistent stack
# replays nothing, so an applied file edited later must be noticed (TRIAL_STACK.md §3.4).
write_manifest() {
local applied f
applied="$(applied_versions)"
( umask 077
for f in supabase/migrations/*.sql; do
if grep -qx "$(file_version "$f")" <<<"$applied"; then
printf '%s %s %s\n' "$(file_version "$f")" "$(file_sum "$f")" "$(basename "$f")"
fi
done > "$MANIFEST.new" )
[ "$(cut -d' ' -f1 "$MANIFEST.new")" = "$applied" ] \
|| die "an applied migration has no file in this branch: migrations.sha256 not written"
mv -f "$MANIFEST.new" "$MANIFEST"
}
check_manifest() {
local version sum file
[ -f "$MANIFEST" ] || die "migrations.sha256 missing: the applied migrations cannot be checked (pnpm db:trial restore <backup>)"
while read -r version sum file; do
[[ "$version" =~ ^[0-9]{14}$ && "$sum" =~ ^[0-9a-f]{64}$ && "$file" =~ ^[0-9]{14}_[A-Za-z0-9_]+\.sql$ ]] \
|| die "migrations.sha256 is malformed"
[ -f "supabase/migrations/$file" ] || die "applied migration $file is missing from this branch: refused"
[ "$(file_sum "supabase/migrations/$file")" = "$sum" ] \
|| die "applied migration $file was edited after it was applied: refused (migrations are forward-only)"
done < "$MANIFEST"
[ "$(cut -d' ' -f1 "$MANIFEST")" = "$(applied_versions)" ] \
|| die "the database's migration history differs from migrations.sha256 (a migrate stopped part-way?): refused; pnpm db:trial restore <its pre-migrate backup> (pnpm db:trial status lists them)"
}
# Kept although `migration up` would refuse too: this refusal comes before migrate's cold backup
# and its stop/start of the stack.
pending_migrations() { # the branch's files not applied yet; refuses one older than the last applied
local last f
last="$(tail -n 1 "$MANIFEST" | cut -d' ' -f1)"
for f in supabase/migrations/*.sql; do
if grep -q "^$(file_version "$f") " "$MANIFEST"; then continue; fi
[ "$(file_version "$f")" \> "$last" ] || die "$(basename "$f") is older than the last applied migration $last: refused"
basename "$f"
done
}
# The seed folder's own consistency: sheet id, every drawing's size and sha256 against
# assets.json, both declared by equine_draft.sql. Prints "sha256 size" per drawing.
SEED_CHECK='
const fs = require("fs"), path = require("path"), c = require("crypto");
const [dir, sheet] = process.argv.slice(1);
const fail = (why) => { console.error(why); process.exit(1); };
const ref = JSON.parse(fs.readFileSync(path.join(dir, "sheet-ref.json"), "utf8"));
const assets = JSON.parse(fs.readFileSync(path.join(dir, "assets.json"), "utf8"));
const seed = fs.readFileSync(path.join(dir, "equine_draft.sql"), "utf8");
if (ref.sheet_id !== sheet || !seed.includes(sheet)) fail("the seed does not name the historical sheet");
if (!Array.isArray(assets) || assets.length === 0) fail("assets.json lists no drawing");
for (const a of assets) {
if (!/^[0-9a-f]{64}$/.test(a.sha256) || !Number.isInteger(a.byte_size)) fail("assets.json entry malformed");
const bytes = fs.readFileSync(path.join(dir, "assets", path.basename(String(a.file))));
if (bytes.length !== a.byte_size || c.createHash("sha256").update(bytes).digest("hex") !== a.sha256)
fail(a.file + " differs from assets.json");
if (!seed.includes(a.sha256)) fail("equine_draft.sql does not declare " + a.file);
console.log(a.sha256 + " " + a.byte_size);
}
'
check_seed_sources() {
node -e "$SEED_CHECK" "$SEED" "$HISTORICAL_SHEET" >/dev/null || die "the equine seed folder fails its own hashes: nothing was created"
}
expected_assets() { node -e "$SEED_CHECK" "$SEED" "$HISTORICAL_SHEET" | LC_ALL=C sort; }
# The Rust pipeline regenerates the seed from the legacy sources and compares it byte for byte
# (R5.6 fingerprint convention): what is loaded is what the pipeline produces. Both checks stay:
# check_seed_sources (folder vs its own hashes, cheap, also in plan) then this one (folder vs
# pipeline); verify_equine_db then checks the database against the folder.
check_seed_pipeline() {
say "equine seed: the Rust pipeline regenerates it and compares (the first run compiles)"
( unset INIT_CWD; bash scripts/import-equine.sh --check ) \
|| die "the equine seed differs from what the pipeline produces: nothing was created"
}
seed_equine() { sb_psql --single-transaction < "$SEED/equine_draft.sql" >/dev/null; }
asset_rows() {
sb_psql -t -A -c "-- db-trial:asset-rows
select sha256 || ' ' || byte_size from public.anatomical_sheet_assets
where sheet_id = private.historical_sheet_id() order by sha256 collate \"C\""
}
uploaded_count() {
sb_psql -t -A -c "-- db-trial:assets-uploaded
select count(*) from public.anatomical_sheet_assets a
where a.sheet_id = private.historical_sheet_id() and a.uploaded_at is not null
and exists (select 1 from storage.objects o
where o.bucket_id = 'anatomical-sheet-assets' and o.name = a.sha256 || '.svg')"
}
# Right after the seed: the historical sheet is the only official one, its single version is a
# draft equal to document.json (jsonb equality, so the canonical fingerprint recorded in
# sheet-ref.json holds), its drawing rows match assets.json, and no account exists.
# A dollar-quote tag, never expanded:
# shellcheck disable=SC2016
DOC_TAG='$faunosteo_trial_doc$'
verify_equine_db() {
local got want="official=1 historical=1 versions=1 draft_equal=true accounts=0"
! grep -qF "$DOC_TAG" "$SEED/document.json" || die "document.json contains $DOC_TAG: cannot compare"
got="$( { cat <<'SQL'
-- db-trial:equine
select concat_ws(' ',
'official=' || (select count(*) from public.anatomical_sheets where is_official),
'historical=' || (select count(*) from public.anatomical_sheets s
where s.id = private.historical_sheet_id() and s.id = :'sheet'::uuid and s.is_official),
'versions=' || (select count(*) from public.anatomical_sheet_versions v
where v.sheet_id = private.historical_sheet_id()),
'draft_equal=' || coalesce((select (v.content =
SQL
printf '%s' "$DOC_TAG"
cat "$SEED/document.json"
printf '%s' "$DOC_TAG"
cat <<'SQL'
::jsonb)::text from public.anatomical_sheet_versions v
where v.sheet_id = private.historical_sheet_id() and v.status = 'draft'), 'none'),
'accounts=' || (select count(*) from auth.users));
SQL
} | sb_psql -t -A -v sheet="$HISTORICAL_SHEET")"
[ "$got" = "$want" ] || die "the equine sheet in the database is not the seed's ($got; expected $want)"
[ "$(asset_rows)" = "$(expected_assets)" ] || die "the equine drawing rows differ from assets.json"
say "equine sheet loaded: $got; drawing rows match assets.json"
}
inventory_counts() {
sb_psql -t -A -F ': ' <<'SQL'
-- db-trial:inventory
select 'accounts', count(*) from auth.users
union all select 'official sheets', count(*) from public.anatomical_sheets where is_official
union all select 'sheet versions', count(*) from public.anatomical_sheet_versions
union all select 'workspaces', count(*) from public.workspaces;
SQL
}
list_backups() { # a folder without SHA256SUMS never finished: listed, marked, never restored
local dir kind
say "backups in $BACKUPS"
[ -d "$BACKUPS" ] || return 0
for dir in "$BACKUPS"/*/; do
[ -d "$dir" ] || continue
if [ -f "$dir/SHA256SUMS" ]; then kind=complete; else kind=incomplete; fi
printf ' %s %s %s\n' "$(basename "$dir")" "$(du -sh "$dir" | cut -f1)" "$kind"
done
}
# plan: each section prints its lines and appends its refusals to the array named by $1.
plan_container_line() { # name
local host inner memory pids
read -r host inner <<<"$(port_of "$1")"
read -r memory pids <<<"$(limits_of "$1")"
printf ' %-24s %-46s 127.0.0.1:%s -> %-5s --memory %-5s --pids-limit %-4s volume %s\n' \
"$1" "$(image_of "$1")" "$host" "$inner" "$memory" "$pids" "$(mount_of "$1")"
}
plan_containers() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local name
echo "Containers (network $NET, restart policy no, --cpus 1):"
for name in "${CONTAINERS[@]}"; do
plan_container_line "$name"
if container_exists "$name"; then refs+=("container $name already exists"); fi
done
echo " $HELPER (create's image check, backup, restore, destroy only): --rm, --network none, image $IMAGE_DB"
}
plan_network_volumes() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local root vol
echo "Network: $NET"
if network_exists "$NET"; then refs+=("network $NET already exists"); fi
root="$(docker info --format '{{.DockerRootDir}}' 2>/dev/null || echo '<Docker data root>')"
echo "Volumes:"
for vol in "$VOL_DB" "$VOL_STORAGE"; do
printf ' %-24s %s/volumes/%s/_data\n' "$vol" "$root" "$vol"
if volume_exists "$vol"; then refs+=("volume $vol already exists"); fi
done
}
plan_images() {
local image where
echo "Images:"
for image in "$IMAGE_DB" "$IMAGE_AUTH" "$IMAGE_REST" "$IMAGE_STORAGE" "$IMAGE_MAIL" "$IMAGE_GATEWAY"; do
if docker image inspect -f '{{.Id}}' "$image" >/dev/null 2>&1; then where=present; else where='not pulled yet (create pulls it)'; fi
printf ' %-46s %s\n' "$image" "$where"
done
}
plan_ports() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local name host inner owner
echo "Ports (127.0.0.1 only):"
for name in "${CONTAINERS[@]}"; do
read -r host inner <<<"$(port_of "$name")"
if port_listening "$host"; then
owner="$(docker ps --format '{{.Names}} {{.Ports}}' 2>/dev/null | grep -F ":$host->" | cut -d' ' -f1 | head -n 1 || true)"
printf ' %-6s taken by %s\n' "$host" "${owner:-a process outside Docker}"
refs+=("port 127.0.0.1:$host is taken")
else
printf ' %-6s free\n' "$host"
fi
done
}
plan_app_host() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local host where
if host="$( (trial_host) 2>&1)"; then
if port_listening "$PORT_APP"; then where=taken; else where=free; fi
echo "App (pnpm db:trial app): http://$host:$PORT_APP, $where; the host is decided again at each app run"
else
refs+=("$host")
fi
}
plan_state_and_disk() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local where="$STATE"
echo "State folder: $STATE (700, secrets 600)"
if [ -f "$SECRETS" ]; then refs+=("$STATE already holds a stack"); fi
echo "Backups: $BACKUPS (cold copies, never pruned by the script; each needs free space of 110 % of the volumes)"
while [ ! -e "$where" ]; do where="$(dirname "$where")"; done
echo "Free disk there: $(df -h --output=avail "$where" | tail -n 1 | tr -d ' ')"
}
plan_memory_and_seed() { # refusals-array
# shellcheck disable=SC2178 # a nameref to the caller's array
local -n refs=$1
local mib
mib="$(available_mib)"
echo "Memory: caps 1920 MiB in all (about 650 MiB used in practice), $mib MiB available, floor $MEMORY_FLOOR_MIB MiB; the app's Node heap is capped at 768 MiB"
if [ "$mib" -lt "$MEMORY_FLOOR_MIB" ]; then refs+=("only $mib MiB of memory available"); fi
if (check_seed_sources) 2>/dev/null; then echo "Equine seed folder: sheet id and drawing hashes match"
else refs+=("the equine seed folder fails its hashes"); fi
echo "At create, before anything is made: the Rust pipeline regenerates the seed and compares it (pnpm r5:import-equine --check), then a --rm helper with no network checks that $IMAGE_DB holds tar and du"
}
cmd_plan() {
[ $# -eq 0 ] || die "plan takes no argument"
local refusals=()
say "db:trial plan: read-only, nothing is created, started or changed"
echo "Docker endpoint: $(daemon_endpoint) (a local unix socket, checked at dispatch)"
if daemon_ok; then echo "Docker daemon: reachable"
else refusals+=("the Docker daemon is unreachable (every Docker answer below is unknown)"); fi
plan_containers refusals
plan_network_volumes refusals
plan_images
plan_ports refusals
plan_app_host refusals
plan_state_and_disk refusals
plan_memory_and_seed refusals
if [ "${#refusals[@]}" -eq 0 ]; then
say "create would proceed"
else
say "create would refuse:"
printf ' - %s\n' "${refusals[@]}"
fi
}
# The backups run tar and du in the database image: proven before anything is made.
check_helper_image() {
docker run --rm --name "$HELPER" --network none --entrypoint sh "$IMAGE_DB" -c 'command -v tar && command -v du' >/dev/null \
|| die "helper check failed: the image lacks tar or du, or a $HELPER container is left over (docker rm $HELPER)"
}
# Before the first Docker resource, the files this create wrote are removed (none existed: create
# refuses a folder holding secrets.env). FIRST_RESOURCE is set just before the first Docker create,
# so a create that died after making something is never mistaken for one that made nothing: past
# it, the files go only when no faunosteo_trial_ resource exists; else nothing is removed and the
# way out is named.
create_stopped() { # cleared on success: a run of the trap is always a failure
local present
present=''
if [ "$FIRST_RESOURCE" = yes ]; then present="$(existing_resources 2>/dev/null)" || present=unknown; fi
if [ -z "$present" ]; then
remove_live_files
echo "db-trial: create stopped before any Docker resource existed; the state files it wrote are removed" >&2
return 0
fi
echo "db-trial: create stopped before the end; nothing was removed. Present now:" >&2
existing_resources | sed 's/^/ /' >&2
echo "pnpm db:trial status shows the state; pnpm db:trial destroy (after the owner's go) backs the data up and clears it, or names the manual removal when it cannot back up." >&2
}
FIRST_RESOURCE=no
# Everything that can refuse comes first: no file, no Docker write yet.
create_preflight() {
local found
[ ! -f "$SECRETS" ] || die "$STATE already holds a trial stack (pnpm db:trial status)"
found="$(existing_resources | tr '\n' ' ')"
[ -z "$found" ] || die "these faunosteo_trial_ resources already exist, nothing was created: $found"
ports_free "${CONTAINERS[@]}"
memory_ok
trial_host >/dev/null
check_seed_sources
check_seed_pipeline
check_helper_image
}
# The lock comes right after the folder exists; the secrets check is repeated under it.
create_state_folder() {
( umask 077; mkdir -p "$STATE" "$BACKUPS" )
chmod 700 "$STATE" "$BACKUPS"
take_lock
[ ! -f "$SECRETS" ] || die "$STATE already holds a trial stack (pnpm db:trial status)"
( umask 077; : > "$MARKER" )
}
create_state_files() {
new_secrets_file "$SECRETS"
load_secrets
write_conf
write_env_files
}
create_docker_resources() {
FIRST_RESOURCE=yes
docker network create --label faunosteo.stack=trial "$NET" >/dev/null
docker volume create --label faunosteo.stack=trial "$VOL_DB" >/dev/null
docker volume create --label faunosteo.stack=trial "$VOL_STORAGE" >/dev/null
}
create_database() {
local name
for name in "$DB" "$MAIL" "$AUTH" "$STORAGE"; do run_service "$name"; done
published_exactly "$DB"
migrate_up
write_manifest
seed_equine
verify_equine_db
}
create_front() {
local name
for name in "$REST" "$GATEWAY"; do run_service "$name"; done
check_loopback
}
cmd_create() {
[ $# -eq 0 ] || die "create takes no argument"
create_preflight
create_state_folder
trap create_stopped EXIT
create_state_files
create_docker_resources
create_database
create_front
trap - EXIT
say "trial stack created and running (gateway http://127.0.0.1:$PORT_GATEWAY)"
echo "Next: pnpm db:trial assets, then the accounts (SUPABASE.md §5.2), then pnpm db:trial app"
}
cmd_start() {
[ $# -eq 0 ] || die "start takes no argument"
require_created
take_lock
memory_ok
start_containers
say "trial stack running; the app: pnpm db:trial app"
}
cmd_stop() {
[ $# -eq 0 ] || die "stop takes no argument"
require_created
take_lock
# A running app would keep proxying session tokens to whatever answers 58801 next.
refuse_while_app_runs
stop_containers
say "trial stack stopped; data kept in $VOL_DB and $VOL_STORAGE"
}
status_migrations() {
local check pending
say "migrations: $(applied_versions | grep -c .) applied, $(find supabase/migrations -maxdepth 1 -name '*.sql' | wc -l) files in this branch"
if check="$( (check_manifest) 2>&1)"; then
# A refusal of pending_migrations is printed as it is, never fatal here.
pending="$( (pending_migrations) 2>&1 | tr '\n' ' ' || true)"
echo " applied files unchanged; new: ${pending:-none}"
else
echo " $check"
fi
}
status_sheet() {
say "equine sheet (versions by status)"
sb_psql -t -A -c "-- db-trial:equine-status
select status::text || ' ' || count(*) from public.anatomical_sheet_versions
where sheet_id = private.historical_sheet_id() group by status order by 1" | sed 's/^/ /'
echo " drawings uploaded and confirmed: $(uploaded_count)/$(expected_assets | grep -c .)"
}
status_accounts() {
say "accounts (email | platform roles | catalogue rights | verified TOTP factors)"
sb_psql -t -A -F ' | ' <<'SQL' | sed 's/^/ /'
-- db-trial:accounts
select u.email,
coalesce((select string_agg(r.role::text, ',' order by r.role::text) from public.profile_roles r
where r.user_id = u.id and r.revoked_at is null), '-'),
coalesce((select string_agg(g.grant_kind::text, ',' order by g.grant_kind::text)
from public.anatomical_catalog_grants g
where g.user_id = u.id and g.revoked_at is null
and (g.expires_at is null or g.expires_at > now())), '-'),
(select count(*) from auth.mfa_factors f
where f.user_id = u.id and f.factor_type = 'totp' and f.status = 'verified')
from auth.users u order by u.email;
SQL
}
status_database() {
status_migrations
status_sheet
status_accounts
say "content"
inventory_counts | sed 's/^/ /'
}
status_containers() {
local name
say "containers"
for name in "${CONTAINERS[@]}"; do
printf ' %-24s %s\n' "$name" "$(docker container inspect -f '{{.State.Status}} {{.Config.Image}}' "$name" 2>/dev/null || echo absent)"
done
}
status_keys_and_host() {
local host
say "keys valid until $(key_expiry) (pnpm db:trial rotate-keys renews them)"
if [ "$(key_check "$TR_ANON_KEY" anon fresh >/dev/null 2>&1; echo $?)" = 3 ]; then
say "the keys have EXPIRED: app, assets and account refuse until pnpm db:trial rotate-keys"
fi
host="$( (trial_host) 2>&1 || true)"
say "app host now: $host (pnpm db:trial app serves http://<host>:$PORT_APP)"
}
status_without_stack() {
say "no trial stack in $STATE (pnpm db:trial plan shows what create would make)"
existing_resources | sed 's/^/ present anyway: /'
list_backups
}
# Only that it exists, never what it holds.
status_leftover_rotation() {
if [ -e "$STATE/secrets.next.env" ]; then
say "secrets.next.env exists: a rotate-secrets stopped part-way and rotate-secrets refuses until it is dealt with (pnpm db:trial restore <pre-rotate backup>)"
fi
}
cmd_status() {
[ $# -eq 0 ] || die "status takes no argument"
if [ ! -e "$MARKER" ] || [ ! -f "$SECRETS" ]; then status_without_stack; return 0; fi
check_private "$STATE" 700
load_conf
load_secrets
status_containers
say "Docker endpoint: $(daemon_endpoint)"
status_keys_and_host
status_leftover_rotation
if container_running "$DB"; then status_database; else say "database stopped: pnpm db:trial start"; fi
list_backups
}
# The exact phrase, typed at a terminal: piped stdin (an agent, a script) is refused before the
# prompt; anything else typed, or nothing, stops too.
confirm() { # phrase
local typed=''
[ -t 0 ] || die "a typed confirmation needs a terminal (stdin is not one): nothing was changed"
printf 'Type "%s" to go on (anything else stops): ' "$1" >&2
read -r typed || true
[ "$typed" = "$1" ] || die "not confirmed: nothing was changed"
}
# Every name a backup folder may hold: a failed backup removes exactly these, then the folder.
BACKUP_FILES=(db.tar storage.tar secrets.env secrets.next.env stack.conf migrations.sha256 SHA256SUMS SHA256SUMS.new)
new_backup_dir() { # label → a fresh folder (700)
local base dir n=1
# A link would send the archives wherever it points.
[ ! -L "$BACKUPS" ] || die "$BACKUPS is a symbolic link: refused, nothing was changed"
base="$BACKUPS/$(date -u +%Y%m%dT%H%M%SZ)-$1"
dir="$base"
while [ -e "$dir" ]; do n=$((n + 1)); dir="$base-$n"; done
( umask 077; mkdir -p "$BACKUPS"; mkdir "$dir" ) || die "cannot create $dir"
printf '%s' "$dir"
}
# Size in KiB and entry count of a volume, by the helper (read-only, no network); the entries are
# counted from the root tar archives, so the archive must list as many.
volume_measure() { # volume → "<KiB> <entries>"
docker run --rm --name "$HELPER" --network none -v "$1:/volume:ro" --entrypoint sh "$IMAGE_DB" \
-c 'du -sk /volume | cut -f1 && cd /volume && find . ! -type s | wc -l' | tr '\n' ' '
}
# The listing of an archive cut at a member boundary still exits 0: its entry count is compared.
backup_volume() { # dir volume entries
local file="$1/${2#faunosteo_trial_}.tar" listed
( umask 077
docker run --rm --name "$HELPER" --network none -v "$2:/volume:ro" --entrypoint tar "$IMAGE_DB" \
--numeric-owner -C /volume -cf - . > "$file" ) || return 1
listed="$(tar -tf "$file" | wc -l)" || return 1
[ "$listed" -eq "$3" ]
}
# A caller that cannot go on without its backup (destroy) names a function that prints the way
# out; backup_failed appends it, so the one failure message stays one message.
BACKUP_WAY_OUT=''
backup_failed() { # dir why: this run's files go by name, then the (now empty) folder
local f
trap - EXIT
for f in "${BACKUP_FILES[@]}"; do rm -f -- "$1/$f"; done
rmdir -- "$1" 2>/dev/null || true
die "backup failed ($2): nothing kept, the stack stays stopped (pnpm db:trial start)${BACKUP_WAY_OUT:+
$($BACKUP_WAY_OUT '')}"
}
# An exit that is not backup_failed's (Ctrl+C, a failing command): the folder stays, unfinished.
BACKUP_RUNNING=''
# Cleared on success and by backup_failed, so a run of the trap is always a failure (its $? is not
# reliable: a SIGTERM leaves 0 in it).
backup_interrupted() {
echo "db-trial: backup $(basename "$BACKUP_RUNNING") is incomplete (no SHA256SUMS: status lists it as incomplete, restore refuses it); the stack may be stopped (pnpm db:trial start)" >&2
}
# Cold copy of every trial volume that exists, with the state files present (the volumes are the
# data, the files only follow): the stack stops, the volumes are measured and free space checked,
# each volume is archived read-only by a --rm helper with no network and its listing must hold
# as many entries as the volume, then the checksums are written last
# (a folder without SHA256SUMS never finished). The stack restarts if it ran and the caller asks.
backup_now() { # label restart(yes|no) → LAST_BACKUP
local dir name vol kib entries i free need=0 vols=() counts=() was_running=no
for name in "${CONTAINERS[@]}"; do if container_running "$name"; then was_running=yes; fi; done
for vol in "$VOL_DB" "$VOL_STORAGE"; do if volume_exists "$vol"; then vols+=("$vol"); fi; done
[ "${#vols[@]}" -gt 0 ] || die "no trial volume to back up"
# A helper left over would collide with every archive run below, after the stack stopped.
if container_exists "$HELPER"; then
die "a $HELPER container is left over (docker rm $HELPER): refused, nothing was changed"
fi
dir="$(new_backup_dir "$1")"
BACKUP_RUNNING="$dir"
trap backup_interrupted EXIT
stop_containers
for vol in "${vols[@]}"; do
read -r kib entries <<<"$(volume_measure "$vol")"
if ! [[ "$kib" =~ ^[0-9]+$ && "$entries" =~ ^[0-9]+$ ]]; then backup_failed "$dir" "measure of $vol"; fi
need=$((need + kib))
counts+=("$entries")
done
# The backups share the disk of Docker's data root (DEV, the sandbox): never fill it.
free="$(df -Pk "$dir" | awk 'NR == 2 { print $4 }')"
if ! [[ "$free" =~ ^[0-9]+$ ]] || [ "$free" -lt $((need * 11 / 10)) ]; then
backup_failed "$dir" "less free space under $BACKUPS than 110 % of the volumes"
fi
for i in "${!vols[@]}"; do
backup_volume "$dir" "${vols[$i]}" "${counts[$i]}" || backup_failed "$dir" "archive of ${vols[$i]} unreadable or incomplete"
done
for name in secrets.env secrets.next.env stack.conf migrations.sha256; do
if [ -f "$STATE/$name" ]; then cp -p "$STATE/$name" "$dir/" || backup_failed "$dir" "copy of $name"; fi
done
( cd "$dir" && umask 077 && sha256sum -- * > SHA256SUMS.new && mv SHA256SUMS.new SHA256SUMS ) \
|| backup_failed "$dir" "checksums"
LAST_BACKUP="$dir"
trap - EXIT
if [ "$2" = yes ] && [ "$was_running" = yes ]; then start_containers; fi
say "backup $(basename "$dir") ($(du -sh "$dir" | cut -f1)) in $BACKUPS"
}
cmd_backup() {
[ $# -eq 0 ] || die "backup takes no argument"
require_state
take_lock
require_created
backup_now manual yes
}
secret_digest() { grep -E '^TR_(PW|JWT_SECRET)=' "$1" | sha256sum | cut -d' ' -f1; }
# The caller says what became of the stack ("nothing was changed", "the stack stays stopped"):
# these checks also run after a backup was taken, when that sentence differs.
refuse_backup() { # dir reason [outcome]
die "backup $(basename "$1") $2${3:+: $3}"
}
# What a restore may trust of a folder: exactly the files its checksums cover, all regular, all
# matching, every archive readable. Run again right before the extraction (the folder is a
# user-writable place: time of check against time of use).
verify_backup_integrity() { # dir [outcome]
local dir="$1" outcome="${2:-}" present listed archive
if [ -L "$BACKUPS" ] || [ -L "$dir" ]; then refuse_backup "$dir" "is reached through a symbolic link" "$outcome"; fi
[ -f "$dir/SHA256SUMS" ] || refuse_backup "$dir" "is incomplete (no SHA256SUMS)" "$outcome"
[ -z "$(find "$dir" -mindepth 1 ! -type f)" ] \
|| refuse_backup "$dir" "holds a symbolic link or an entry that is not a regular file" "$outcome"
present="$(find "$dir" -mindepth 1 ! -name SHA256SUMS -printf '%f\n' | LC_ALL=C sort)"
listed="$(sed 's/^[0-9a-f]\{64\} //' "$dir/SHA256SUMS" | LC_ALL=C sort)"
[ "$present" = "$listed" ] \
|| refuse_backup "$dir" "has a SHA256SUMS that does not list exactly the files of its folder" "$outcome"
( cd "$dir" && sha256sum --quiet --strict -c SHA256SUMS ) || refuse_backup "$dir" "fails its checksums" "$outcome"
for archive in "$dir"/*.tar; do
tar -tf "$archive" >/dev/null 2>&1 || refuse_backup "$dir" "holds an unreadable archive ($(basename "$archive"))" "$outcome"
done
}
first_absent_image() { # the recorded IMAGE_* (parse_conf ran), the first one not here; nothing when all are
local image
for image in "$IMAGE_DB" "$IMAGE_AUTH" "$IMAGE_REST" "$IMAGE_STORAGE" "$IMAGE_MAIL" "$IMAGE_GATEWAY"; do
if ! docker image inspect -f '{{.Id}}' "$image" >/dev/null 2>&1; then printf '%s' "$image"; return 0; fi
done
}
# Restorable: the folder is intact, both archives, the secrets and stack.conf are there and
# parse, the keys are signed with the backup's own secret and the six images it recorded are here.
check_backup() { # dir [outcome]
local dir="$1" outcome="${2:-}" file image
verify_backup_integrity "$dir" "$outcome"
for file in db.tar storage.tar secrets.env stack.conf; do
[ -f "$dir/$file" ] || refuse_backup "$dir" "lacks $file" "$outcome"
done
( parse_secrets "$dir/secrets.env" && parse_conf "$dir/stack.conf" ) 2>/dev/null \
|| refuse_backup "$dir" "holds incomplete secrets or stack.conf" "$outcome"
# Its keys must be signed with its own secret (expiry aside: rotate-keys renews them after).
( parse_secrets "$dir/secrets.env" && key_check "$TR_ANON_KEY" anon any "$TR_JWT_SECRET" \
&& key_check "$TR_SERVICE_KEY" service_role any "$TR_JWT_SECRET" ) >/dev/null 2>&1 \
|| refuse_backup "$dir" "holds keys that are not signed with its own secret" "$outcome"
image="$(parse_conf "$dir/stack.conf"; first_absent_image)"
[ -z "$image" ] || refuse_backup "$dir" "records an image that is not present locally ($image: docker pull it first)" "$outcome"
}
# The pre-restore backup, when one was taken: the way back if the restore stops part-way.
PRE_RESTORE=''
RESTORE_TARGET=''
restore_stopped() { # cleared on success: a run of the trap is always a failure
echo "db-trial: restore stopped part-way: containers and volumes may be missing or half-filled." >&2
if [ -n "$PRE_RESTORE" ]; then
echo "The state before it is backup $(basename "$PRE_RESTORE"): pnpm db:trial restore $(basename "$PRE_RESTORE")" >&2
else
echo "No backup of the state before it was taken (there was no trial volume)." >&2
fi
echo "The same restore can be rerun: pnpm db:trial restore $RESTORE_TARGET" >&2
}
# A restore must stay possible over a damaged stack: the pre-restore backup only has to be
# intact (it is the way back); when a restore would refuse it as it is, the owner is told.
check_pre_restore_backup() {
local note
verify_backup_integrity "$LAST_BACKUP" "nothing was removed, the stack stays stopped (pnpm db:trial start)"
if ! note="$(check_backup "$LAST_BACKUP" 2>&1)"; then
echo "note: the backup before this restore keeps both volumes, but restore will refuse it as it is (${note#db-trial: })"
fi
if [ -f "$LAST_BACKUP/secrets.next.env" ]; then
echo "note: that backup also holds a leftover secrets.next.env (a rotate-secrets stopped part-way): restoring it brings the file back"
fi
}
# Rebuilds the stack from <backup>: volumes and secrets replaced, containers recreated from the
# images the backup recorded. Works on a destroyed stack too (backups survive destroy).
cmd_restore() {
local name="${1:-}" dir vol f
[ $# -eq 1 ] && [[ "$name" =~ ^[0-9]{8}T[0-9]{6}Z-[a-z0-9-]+$ ]] \
|| die "restore <backup>: the name of a folder in $BACKUPS (pnpm db:trial status lists them)"
require_state
take_lock
dir="$BACKUPS/$name"
[ ! -L "$BACKUPS" ] || die "$BACKUPS is a symbolic link: refused, nothing was changed"
[ ! -L "$dir" ] || die "backup $name is a symbolic link: refused, nothing was changed"
[ -d "$dir" ] || die "no backup $name in $BACKUPS"
check_backup "$dir" "nothing was changed"
refuse_while_app_runs
# Without a trial volume backup_now's own helper check does not run: refused here, before the confirmation.
if container_exists "$HELPER"; then
die "a $HELPER container is left over (docker rm $HELPER): refused, nothing was changed"
fi
if [ -f "$CONF" ]; then parse_conf "$CONF" || true; fi
if [ -f "$SECRETS" ] && [ "$(secret_digest "$SECRETS")" != "$(secret_digest "$dir/secrets.env")" ]; then
echo "note: backup $name holds other secrets than the current ones (taken before a rotate-secrets?): the restore brings them back"
fi
echo "restore replaces the trial stack's data and secrets by backup $name. Present now:"
existing_resources | sed 's/^/ /'
confirm "restore $name"
if volume_exists "$VOL_DB" || volume_exists "$VOL_STORAGE"; then
backup_now pre-restore no
PRE_RESTORE="$LAST_BACKUP"
check_pre_restore_backup
else
echo "no trial volume: nothing to back up before the restore"
fi
RESTORE_TARGET="$name"
stop_containers
# Armed once nothing can refuse any more: a refusal above touched no container or volume.
ports_free "${CONTAINERS[@]}"
trap restore_stopped EXIT
remove_containers
parse_conf "$dir/stack.conf"
verify_backup_integrity "$dir"
for vol in "$VOL_DB" "$VOL_STORAGE"; do
if volume_exists "$vol"; then docker volume rm "$vol" >/dev/null; fi
docker volume create --label faunosteo.stack=trial "$vol" >/dev/null
docker run --rm -i --name "$HELPER" --network none -v "$vol:/volume" --entrypoint tar "$IMAGE_DB" \
--numeric-owner -xpf - -C /volume < "$dir/${vol#faunosteo_trial_}.tar"
done
remove_live_files
for f in secrets.env secrets.next.env stack.conf migrations.sha256; do
if [ -f "$dir/$f" ]; then write_private "$STATE/$f" < "$dir/$f"; fi
done
load_conf
load_secrets
start_containers
trap - EXIT
say "restored $(basename "$dir")${PRE_RESTORE:+; the state before it: $(basename "$PRE_RESTORE")}"
}
# What destroy tells the owner when it refuses for want of a restorable backup: the backup kept
# (or none), the removals the owner may run by hand for what exists now, then the state files.
# The script never runs these itself.
destroy_way_out_line() { # kind command
local names
names="$(existing_resources | sed -n "s/^$1 //p" | tr '\n' ' ')"
if [ -n "$names" ]; then echo " $2 ${names% }"; fi
}
destroy_way_out() { # kept backup folder, or empty
if [ -n "$1" ]; then echo "backup $(basename "$1") is kept."; else echo "no backup could be made."; fi
echo "Nothing was removed. To remove the stack yourself, run by hand:"
destroy_way_out_line container 'docker rm'
destroy_way_out_line network 'docker network rm'
destroy_way_out_line volume 'docker volume rm'
echo "then pnpm db:trial destroy clears the state files (backups kept)."
}
DESTROY_BACKUP=''
destroy_stopped() { # cleared on success: a run of the trap is always a failure
echo "db-trial: destroy stopped part-way: containers, the network or volumes may remain (pnpm db:trial status)." >&2
echo "Its backup $(basename "$DESTROY_BACKUP") is kept: pnpm db:trial restore $(basename "$DESTROY_BACKUP") rebuilds the stack; pnpm db:trial destroy can be rerun." >&2
}
cmd_destroy() {
[ $# -eq 0 ] || die "destroy takes no argument"
local found vol
require_state
take_lock
refuse_while_app_runs
if [ -f "$CONF" ]; then parse_conf "$CONF" || true; fi
found="$(existing_resources)"
if [ -z "$found" ]; then
echo "no faunosteo_trial_ resource exists: destroy removes the live state files of $STATE (backups kept)"
confirm faunosteo_trial
remove_live_files
say "live state files removed; backups kept in $BACKUPS"
return 0
fi
echo "destroy removes:"
printf '%s\n' "$found" | sed 's/^/ /'
if container_running "$DB" && ( parse_secrets "$SECRETS" ) 2>/dev/null; then
load_secrets
echo "content:"
# A damaged database must not stop the destroy that gets rid of it.
{ inventory_counts || echo "(content unreadable)"; } | sed 's/^/ /'
fi
echo "kept: every backup in $BACKUPS, including the one taken now"
confirm faunosteo_trial
if volume_exists "$VOL_DB" || volume_exists "$VOL_STORAGE"; then
BACKUP_WAY_OUT=destroy_way_out
backup_now pre-destroy no
BACKUP_WAY_OUT=''
check_backup "$LAST_BACKUP" "the stack stays stopped (pnpm db:trial start)
$(destroy_way_out "$LAST_BACKUP")"
DESTROY_BACKUP="$LAST_BACKUP"
trap destroy_stopped EXIT
fi
stop_containers
remove_containers
if network_exists "$NET"; then docker network rm "$NET" >/dev/null; fi
for vol in "$VOL_DB" "$VOL_STORAGE"; do if volume_exists "$vol"; then docker volume rm "$vol" >/dev/null; fi; done
remove_live_files
trap - EXIT
say "trial stack destroyed; backups kept in $BACKUPS"
}
migrate_stopped() { # cleared on success: a run of the trap is always a failure
echo "db-trial: migrate stopped part-way: pnpm db:trial restore $(basename "$LAST_BACKUP") returns to the state before it" >&2
}
cmd_migrate() {
[ $# -eq 0 ] || die "migrate takes no argument"
local pending
require_state
take_lock
require_running
published_exactly "$DB"
check_manifest
pending="$(pending_migrations)"
[ -n "$pending" ] || { say "no new migration"; return 0; }
echo "new migrations:"
printf '%s\n' "$pending" | sed 's/^/ /'
backup_now pre-migrate yes
check_backup "$LAST_BACKUP" "no migration was applied; the backup is kept and the stack runs"
trap migrate_stopped EXIT
migrate_up
write_manifest
sb_psql -c "-- db-trial:reload
notify pgrst, 'reload schema'" >/dev/null
trap - EXIT
say "migrated; the backup before it: $(basename "$LAST_BACKUP")"
}
keys_stopped() { # cleared on success: a run of the trap is always a failure
echo "db-trial: rotate-keys stopped part-way; secrets.env holds the new keys; pnpm db:trial start recreates a missing container and restarts the gateway" >&2
}
# A backup first (secrets.env included), then new keys signed with the same secret: the expiry moves one year on. The previous keys stay valid
# until their own expiry (rotate-secrets revokes them). Storage holds the keys in its env; the
# gateway restarts after it (nginx resolved the old container's address).
cmd_rotate_keys() {
[ $# -eq 0 ] || die "rotate-keys takes no argument"
local was_running=no
require_state
take_lock
# A created stack is enough, running or stopped: the way out of expired keys must never need
# the keys to be valid.
require_created
refuse_while_app_runs
# Keys that are not this stack's: refused before the backup stops anything.
require_trial_keys
if container_running "$DB"; then was_running=yes; fi
# The same cold, read-back backup as rotate-secrets, before any change, and proven restorable
# (checksums, archives, keys signed with its secret, image) before any key changes.
backup_now pre-keys yes
check_backup "$LAST_BACKUP" "no key was changed; the backup is kept"
if ! ( umask 077
printf 'TR_PW=%s\nTR_JWT_SECRET=%s\n' "$TR_PW" "$TR_JWT_SECRET" > "$SECRETS.new"
TR_JWT_SECRET="$TR_JWT_SECRET" node -e "$KEYGEN" keys >> "$SECRETS.new" ) \
|| ! ( parse_secrets "$SECRETS.new" ); then
rm -f "$SECRETS.new"
die "key generation failed: nothing was changed"
fi
mv -f "$SECRETS.new" "$SECRETS"
# Armed once secrets.env holds the new keys: before it, only the backup and a .new file exist.
trap keys_stopped EXIT
load_secrets
write_env_files
if container_running "$STORAGE"; then docker stop -t 30 "$STORAGE" >/dev/null; fi
if container_exists "$STORAGE"; then docker rm "$STORAGE" >/dev/null; fi
if [ "$was_running" = yes ]; then
run_service "$STORAGE"
restart_gateway
check_loopback
fi
trap - EXIT
say "anon and service keys renewed, valid until $(key_expiry); the app takes the new anon key at its next start"
if [ "$was_running" = no ]; then echo "the stack is stopped: pnpm db:trial start recreates Storage with the new keys"; fi
}
# The branch comes from the state: secrets.next.env is gone once the rename happened, even when the
# signal fell before ROTATION_COMMITTED was set. The trap is armed only once that file exists.
rotation_stopped() { # cleared on success: a run of the trap is always a failure
if [ "$ROTATION_COMMITTED" = yes ] || [ ! -e "$STATE/secrets.next.env" ]; then
echo "db-trial: rotate-secrets stopped after the database took the new secrets; secrets.env holds them." >&2
echo "pnpm db:trial start recreates the missing containers from it." >&2
else
echo "db-trial: rotate-secrets stopped before secrets.env took the new secrets (the database may or may not have them); secrets.env (previous) and secrets.next.env (new) are both kept." >&2
echo "pnpm db:trial restore $(basename "$LAST_BACKUP") returns to the state before it." >&2
fi
}
ROTATION_COMMITTED=no
# The rotation's own database session name, and how long settle_rotation waits for it to end.
ROTATION_APP=db-trial-rotate
ROTATION_WAIT_POLLS=10
# One transaction run as supabase_admin; values through psql variables read from the exec
# environment (never argv, never the SQL text); statement logging off, errors included. The
# transaction is explicit (begin ... commit), not psql --single-transaction: that flag would
# COMMIT a script cut short at end of input, whereas an input cut before `commit;` leaves the
# server to roll the open transaction back. The same transaction records the digest of the new secrets file in a database setting: the only
# trustworthy proof of the commit (password probes over 127.0.0.1 are `trust` in this image's
# pg_hba.conf and succeed whatever the password).
rotate_in_database() { # new password, new JWT secret, digest of the new secrets file
PGPASSWORD="$TR_PW" PGAPPNAME="$ROTATION_APP" NEW_PW="$1" NEW_JWT="$2" ROT_DIGEST="$3" \
docker exec -i -e PGPASSWORD -e PGAPPNAME -e NEW_PW -e NEW_JWT -e ROT_DIGEST "$DB" \
psql -X -q -h 127.0.0.1 -U supabase_admin -d postgres -v ON_ERROR_STOP=1 >/dev/null <<'SQL'
-- db-trial:rotate
begin;
set local log_statement = 'none';
set local log_min_duration_statement = -1;
set local log_min_error_statement = panic;
set local pgaudit.log = 'none';
\set newpw `printf '%s' "$NEW_PW"`
\set newjwt `printf '%s' "$NEW_JWT"`
\set digest `printf '%s' "$ROT_DIGEST"`
alter role supabase_admin with password :'newpw';
alter role postgres with password :'newpw';
alter role authenticator with password :'newpw';
alter role supabase_auth_admin with password :'newpw';
alter role supabase_storage_admin with password :'newpw';
alter database postgres set "app.settings.jwt_secret" to :'newjwt';
alter database postgres set "app.trial_rotation" to :'digest';
commit;
SQL
}
# The setting the rotation transaction wrote, read in a fresh session (a database setting applies
# to new sessions only). Empty when no rotation committed.
rotation_marker() {
sb_psql -t -A -c "-- db-trial:rotation-marker
select coalesce(current_setting('app.trial_rotation', true), '')"
}
# Sessions still named as the rotation's: a transaction whose client is gone stays open until the
# server notices, and may still commit or roll back.
rotation_sessions() {
sb_psql -t -A -c "-- db-trial:rotation-active
select count(*) from pg_stat_activity where application_name = '$ROTATION_APP'"
}
# Waits (a poll a second, at most ROTATION_WAIT_POLLS) for the rotation session to end: 0 once it
# is gone, 1 when it is still there or the database cannot say.
wait_rotation_session_gone() {
local poll count
for ((poll = 1; poll <= ROTATION_WAIT_POLLS; poll++)); do
count="$(rotation_sessions 2>/dev/null)" || return 1
[[ "$count" =~ ^[0-9]+$ ]] || return 1
[ "$count" -eq 0 ] && return 0
if [ "$poll" -lt "$ROTATION_WAIT_POLLS" ]; then sleep 1; fi
done
return 1
}
rotation_unknown() { # why
trap - EXIT
die "$1: whether the rotation committed is unknown; secrets.env (previous) and secrets.next.env (new) are both kept; pnpm db:trial restore $(basename "$LAST_BACKUP") returns to the state before it"
}
# psql failed: did the transaction commit anyway (a dropped exec stream, a daemon hiccup)? Once
# no session of the rotation is left, the marker decides; the new values are dropped only when
# the database answers without it.
settle_rotation() { # next file, digest of it
local marker
wait_rotation_session_gone \
|| rotation_unknown "a rotation session is still active after $ROTATION_WAIT_POLLS checks, or the database does not answer"
marker="$(rotation_marker 2>/dev/null)" || rotation_unknown "the database does not answer"
if [ "$marker" = "$2" ]; then
say "the database took the new secrets although psql failed: the rotation goes on"
return 0
fi
trap - EXIT
rm -f "$1"
die "the database did not take the new secrets: nothing was changed (backup $(basename "$LAST_BACKUP"))"
}
# New JWT secret, keys and role passwords; account passwords and TOTP factors untouched. The
# new values sit in secrets.next.env (600) before the database changes, so they exist somewhere
# whatever happens next (Ctrl+C included: it exits through the EXIT trap, which keeps that file).
cmd_rotate_secrets() {
[ $# -eq 0 ] || die "rotate-secrets takes no argument"
local next="$STATE/secrets.next.env" new_pw new_jwt digest
require_state
take_lock
require_running
# A previous rotation stopped part-way: that file may be the only copy of the secrets the
# database holds, so it is never overwritten.
[ ! -e "$next" ] || die "$next exists: a previous rotate-secrets left it, and it may hold the only copy of the secrets the database took. Never overwritten: pnpm db:trial restore <pre-rotate backup> (pnpm db:trial status lists the backups) is the way back; nothing was changed"
refuse_while_app_runs
# Keys that are not this stack's: refused before the backup stops anything.
require_trial_keys
backup_now pre-rotate yes
# The backup is the only copy of the previous secrets (no secrets.prev): proven restorable first.
check_backup "$LAST_BACKUP" "no secret was changed; the backup is kept"
new_secrets_file "$next" || true
if ! ( parse_secrets "$next" ); then rm -f "$next"; die "secret generation failed: nothing was changed"; fi
trap rotation_stopped EXIT
new_pw="$(sed -n 's/^TR_PW=//p' "$next")"
new_jwt="$(sed -n 's/^TR_JWT_SECRET=//p' "$next")"
digest="$(sha256sum < "$next" | cut -d' ' -f1)"
if ! rotate_in_database "$new_pw" "$new_jwt" "$digest"; then settle_rotation "$next" "$digest"; fi
# Committed means secrets.env holds the new values: set once the rename is done.
mv -f "$next" "$SECRETS"
ROTATION_COMMITTED=yes
load_secrets
# The containers carry the previous values in their env: removed at once, recreated by
# start_containers (which checks every port before any start).
stop_containers
remove_containers
start_containers
trap - EXIT
say "secrets renewed: sessions signed with the old secret are refused (sign in again); account passwords and TOTP factors unchanged; backup before it: $(basename "$LAST_BACKUP")"
}
# Every command's arguments are checked before any Docker call (a refusal here logs nothing).
# The commands keep their own checks too, so each stays safe if called on its own.
check_arguments() { # action args...
local action="$1"
shift
case "$action" in
plan | create | start | stop | status)
[ $# -eq 0 ] || die "$action takes no argument" ;;
migrate | backup | rotate-keys | rotate-secrets | destroy)
[ $# -eq 0 ] || die "$action takes no argument" ;;
restore)
[ $# -eq 1 ] && [[ "$1" =~ ^[0-9]{8}T[0-9]{6}Z-[a-z0-9-]+$ ]] \
|| die "restore <backup>: the name of a folder in $BACKUPS (pnpm db:trial status lists them)" ;;
*) usage; exit 1 ;;
esac
}
guard_environment
action="${1:-}"
[ $# -eq 0 ] || shift
case "$action" in
'' | help | -h | --help) usage; exit 1 ;;
esac
check_arguments "$action" "$@"
command -v docker >/dev/null || die "docker is not installed"
command -v ss >/dev/null || die "ss (iproute2) is not installed: the ports cannot be checked, nothing was run"
require_local_daemon
# Past this line a Docker "absent" is an answer, not a dead daemon (plan reports the daemon itself).
if [ "$action" != plan ]; then
daemon_ok || die "Docker daemon unreachable: nothing was run (systemctl --user status docker)"
fi
case "$action" in
plan) cmd_plan "$@" ;;
create) cmd_create "$@" ;;
start) cmd_start "$@" ;;
stop) cmd_stop "$@" ;;
status) cmd_status "$@" ;;
migrate) cmd_migrate "$@" ;;
backup) cmd_backup "$@" ;;
restore) cmd_restore "$@" ;;
rotate-keys) cmd_rotate_keys "$@" ;;
rotate-secrets) cmd_rotate_secrets "$@" ;;
destroy) cmd_destroy "$@" ;;
*) usage; exit 1 ;;
esac