Appearance
0030: A separate dev database, no Postgres port on the LAN, and how local Claude Code reaches real data
Note 2026-11-06: the git host and CI moved to GitHub (
FEAW-Serv/getmy-books), ADR 0046. References below to the previous host are history; ADR 0046 says what replaces them.
Status
Accepted by the Product Owner on 2026-11-06. DH-9 was decided as recommended the same day: keep the production Xero app, rotate its secret, and add a dev app on the Demo Company.
Proposed, with docs/plans/deploy-hardening.md (slice 3). It depends on ADR 0029, because migrations must stop using the LAN port first. It builds on #63 (separating prd secrets from dev): it answers #63's first question (how dev stops sharing the production database), and it changes #63 step 3 (see decision 4). It amends ADR 0014's statement that the migrate-nas runner reaches the NAS database.
Context
Issue #73. There is one Postgres, on the NAS, used by three things:
- The production app, over the compose network.
- The owner's local Claude Code.
.mcp.jsonruns it with Dopplerdev, and it reaches the database over the LAN at192.168.0.80:5433. migrate-nas, also over the LAN.
The postgres service publishes 5433 on every interface, with password login.
Consequences today:
- Local testing changes production data and the real FEAW Xero.
- Every laptop that holds
devhas the owner password. - Nothing stops the test suite pointing its destructive fixtures at the NAS.
- The local route and the NAS app refresh the same Xero token row, which can race into
invalid_grant.
The local route is also the only route today with:
- Xero writes. (Changed 2026-10-01: the web route now has them too, each approved in the approval card, AUDIT C5.)
- Amex statement files, which are read from the laptop's disk.
- The connect scripts (
xero-connect,starling-connect,statement-account-add), which write to whatever databaseAPP_DATABASE_URLnames.
Decision
- Doppler
devanddev_personalpoint at a local throwaway Postgres (localhost:55432,getmy_books_dev). They get their ownXERO_TOKEN_ENCRYPTION_KEYand a separate Xero app,GetMy Books (dev), that is connected only to Xero's UK Demo Company. They losePOSTGRES_PASSWORDandGETMY_BOOKS_TUNNEL_TOKEN.- The dev entity is named "Demo", never "FEAW", because migration 0005 grants FEAW by name.
- The local stdio server keeps its name until decision 3's spike settles naming. Renaming it breaks CLAUDE.md line 40, README lines 79-80 and tool allowlists. More importantly, once
devis the Demo database, a local server's conversation-start heads-up (SPEC-004) would show Demo's deadlines, not FEAW's. The owner's default Claude Code session must still show FEAW's real heads-up (FEAW's Jun-Aug VAT return is due 7 October) before the split.
- Postgres publishes no port.
- The compose file drops
ports:. - The root compose check refuses
ports:on every service, so a closed port is enforced, not just configured. - Acceptance:
nc -z 192.168.0.80 5433fails from the LAN.
- The compose file drops
- The owner's real FEAW work goes through the deployed endpoint (
https://mcp.getmy.group/mcp, added to Claude Code as an HTTP server and signed in through Cloudflare Access), subject to a spike first. The app reads onlycf-access-jwt-assertion, so this works only if Claude Code completes the Access sign-in. Before this option is confirmed, and before the write gate or the CSV tool is built, a spike checks that sign-in for each owner, how ADR 0020's short sessions behave in Claude Code, and that the FEAW deadline heads-up appears through this route. If it fails, option (b) is reconsidered. The port closes only once that route covers today's local work:- Xero writes: on the web route for named principals only (
XERO_WRITE_PRINCIPALS, in the root-ownedconfig.envon the NAS, not inprdor the deploy env, per ADR 0028). Preview then confirm by ID is unchanged, and no tool files or submits anything (rule 5). This is a product change, made through a spec and the README first. - Amex statement files: a statement tool that takes the CSV content from the client and parses it in pure code, with the entity from the session. It must fit within the approved 1 MiB HTTP request limit (C4) for a full Amex statement, taking the statement in pages if not.
- Reconnecting Xero or Starling for production: a break-glass runbook that runs the compiled connect script in the current image, on the compose network, from an administrator's DSM session. The OAuth callback is forwarded over SSH to
127.0.0.1only. The connect scripts are compiled with their own build config intodist-tools/;tsconfig.build.jsonkeepsrootDir: "src", sodist/main.jsand the image'sCMDandHEALTHCHECKdo not move.
- Xero writes: on the web route for named principals only (
- Separate Xero apps. The dev app is new. The production app stays, and gets a new client secret because the old one sat on laptops. Keeping it avoids reconnecting FEAW. This replaces #63 step 3's "new production app".
- Production passwords are rotated after the split, because they sat in
dev:- The owner password is changed by hand with psql's
\passwordover the container's local socket, so it never appears in shell history, the process list or the Postgres log, then updated in Doppler. - The app password is changed in Doppler. The deploy's migrate step then sets it as a SCRAM verifier (ADR 0029). If that deploy fails
/health, the rollback reuses the new env (ADR 0028), so production stays up.
- The owner password is changed by hand with psql's
- Guards stay in place. Every script and test that takes a database URL refuses any host other than
localhost,127.0.0.1,::1orpostgres. That is the pattern inperf/load/server.ts. - Never copy
xero_connection,bank_account.credentials_encrypted, or a production dump into a dev database. Never connect a dev database to the real FEAW Xero. Theledger_writeduplicate guard must stay single, or a Starling line could be entered twice.
Options considered for local Claude Code
| Option | Verdict |
|---|---|
| (a) The deployed endpoint for real work | Chosen, subject to the spike. No database credentials on laptops; one token refresher; one duplicate guard; identity per person. It needs the Access sign-in from Claude Code to work, then the write gate and the CSV tool |
(b) An SSH tunnel to a loopback-bound Postgres, with a prd_local config | Fallback, if the Product Owner refuses web-route writes. Everything local keeps working, but production app credentials stay on laptops. It needs a forwarding-only DSM user, which DSM resets to /sbin/nologin (#69) |
| (c) A local dev database on the Demo Company | Chosen for development and all agents. It cannot replace real work on its own |
What changes, and where
| Where | Change |
|---|---|
| Repo | .mcp.json; infra/nas/docker-compose.yml (no ports, header comment); infra/nas/deploy/getmy-books-compose-check (refuses ports); the connect scripts compiled into dist-tools/; host guards; README lines 79-84 and CLAUDE.md if the server name changes; docs/dev/local-postgres-tests.md; ADR 0014 |
| Doppler | dev and dev_personal repointed, with a new key, a new Xero app, and production secrets removed; prd POSTGRES_PASSWORD, APP_DB_PASSWORD and XERO_CLIENT_SECRET rotated |
| Xero | New dev app; new production client secret |
| NAS | Compose file and compose check reinstalled; the owner password changed by hand with \password; XERO_WRITE_PRINCIPALS in the root config.env if the write gate is approved (a window) |
| Cloudflare | Nothing expected. The spike confirms that Claude Code completes the Access sign-in to the endpoint |
Consequences
- Development and agents can no longer reach production data, and a stray
pnpm testcannot touch the NAS. - The LAN no longer offers a Postgres login.
- The owner's real work moves to the same endpoint as the claude.ai connector: one database, one Xero refresher, one duplicate guard.
- Until the write gate and the CSV tool ship, the port stays open. After they ship, anything they do not cover (for example a new kind of statement file) needs its own route before it can be used on real data.
- Production reconnects become a rare runbook step. Because it is rarely used, it is easy to get wrong, so it is written down and rehearsed on the dev database.
XERO_TOKEN_ENCRYPTION_KEYfor production was also on laptops, and is in every release env on the NAS next to the dumps. Rotating it needs the re-encrypt tool in #63, and stays open until then. (Changed 2026-11-03, #63: the tool now exists.scripts/reencrypt-credentials.tsmoves every stored credential from the old key to the new one in one transaction, guarded ontoken_version, andscripts/check-encryption-key.tsgives the counts-only check; the steps are in the developer guide, 'Rotate the encryption key'. The production rotation is not done: the Product Owner can now schedule it for a maintenance window.)- Until the owner's route shows FEAW's deadlines at the start of a conversation, the split does not happen: losing that heads-up would be a product regression.