---
name: franksign-worktree-db-cred-trap
description: "Diagnose franksign e2e seam 5 / health 503 db:down in a fresh worktree: setup-dev.sh minted a password that mismatches the shared franksign-db container."
---

# franksign fresh-worktree DB credential trap

## Symptom
`tests/run.sh` in a fresh franksign worktree fails seam 5 ("e2e server did not
become healthy") while the server log says `franksign-api listening on :3100`.
Manual probe shows the server IS up:

```bash
PORT=3100 node --env-file=.env apps/api/dist/cli.js >/tmp/manual-e2e.log 2>&1 &
sleep 2; curl -s http://127.0.0.1:3100/health
# -> 503 {"status":"degraded","db":"down",...}
```

Not a regression, not a :3100 port collision (check `ss -tlnp | grep 3100` to rule that out).

## Root cause
`infra/setup-dev.sh` mints a fresh `POSTGRES_PASSWORD` per checkout
(`if [ ! -f infra/postgres.env ]`), but `franksign-db` + `franksign-pgdata`
are shared box state owned by the main checkout
(`~/Projects/franksign`). The new worktree's `.env` DATABASE_URL then fails
TCP auth against the initialized volume.

The setup script masks it: its readiness gate is
`podman exec franksign-db pg_isready`, which uses the in-container local
socket and passes regardless of password — so setup prints "postgres ready"
while the checkout is dead on arrival.

## Fix (git-ignored files, no commit needed)
Copy the shared credentials from the owning checkout:

```bash
grep DATABASE_URL /home/blank/Projects/franksign/.env   # source of truth
# PUT that exact DATABASE_URL line into this worktree's .env
# PUT the matching POSTGRES_PASSWORD into this worktree's infra/postgres.env
```

Gotcha: the shared password may contain literal `$$`. Keep it byte-for-byte —
systemd `EnvironmentFile` and `node --env-file` both read values literally,
so `$$` in the file IS `$$` in the password. No escaping, no de-escaping.

## Verify
```bash
PORT=3100 node --env-file=.env apps/api/dist/cli.js &  # then
curl -fsS http://127.0.0.1:3100/health   # -> {"status":"ok","db":"up"}
tests/run.sh                             # 14/14
```

## Permanent fix (proposed, not yet landed)
`setup-dev.sh` should reuse `~/.config/containers/systemd/postgres.env`
(symlink to the owning checkout) when present instead of minting new creds.