Appearance
Break-glass: reconnect Xero from the NAS
Issue #73, DH-6 (decided 2026-11-04), ADR 0030 decision 3, plan docs/plans/deploy-hardening.md ("Local Claude Code: the decision"). This is the rare route. Use the web reconnect first.
When this is needed
Both of these must be true:
- A company's Xero connection no longer works: the refresh token has expired or been revoked (
connection_checksays the stored connection no longer sees the company's organisation and to reconnect Xero; three failed refreshes also raise an alert, SPEC-008). - The normal web reconnect (the Xero connect on
/startand/xero, SPEC-017) is itself broken or switched off (XERO_WEB_REDIRECT_URIempty).
If the web route works, use it and stop here.
Who may do it
Only a NAS administrator: the Product Owner or Rob, or an agent acting on their instruction, in one change window at a time (DH-10, ADR 0023). The deploy user cannot: it is not an administrator and not in the docker group. The person named in OPERATOR_EMAIL must have a GetMy Books sign-in with access to the company (ADR 0039).
What it runs
scripts/xero-connect.ts and scripts/statement-account-add.ts are compiled into the production image as /app/dist-tools/scripts/xero-connect.js and /app/dist-tools/scripts/statement-account-add.js (tsconfig.tools.json, the Dockerfile runtime stage, PR #350). They run in a throwaway container of the current image, on the compose network, with the app's own environment from the release .env. Tokens are written straight into the production database, encrypted, and never leave the NAS. docker exec cannot publish a port for the OAuth callback, so this uses compose run, as the plan does (a new container of the same app service, not the running one).
Before you start
- Open a change window (DH-10). Nothing else deploys during it.
- The Xero app must list
http://localhost:8734/callbackas a redirect URI: the script uses it unlessXERO_REDIRECT_URIis set, and the compose file does not set it (src/xero/session.ts,infra/nas/docker-compose.yml). Owner to confirm this is registered in the Xero developer app before the first use. If it is not, stop. - Have the company's exact name as GetMy Books holds it (
ENTITY_NAME) and the operator's email.
Steps
From an administrator's machine, open an SSH session to the NAS that forwards the callback port to the NAS's loopback only:
bashssh -L 8734:127.0.0.1:8734 nasThe laptop only forwards a port and opens a browser. The script does not run on the laptop.
On the NAS, as root, build the same compose command the deploy uses (
infra/nas/deploy/getmy-books-up):bashsudo -i release="$(realpath -e /var/services/homes/deploy/getmy-books/current)" project=(docker compose -p getmy-books \ -f /usr/local/etc/getmy-books/docker-compose.yml \ --project-directory "$release/infra/nas" \ --env-file "$release/infra/nas/.env")getmy-books-upfalls back todocker-composeifdocker compose versiondoes not work; do the same here.Run the compiled script. Replace the two values:
bash"${project[@]}" run --rm --no-deps -p 127.0.0.1:8734:8734 \ -e OPERATOR_EMAIL=person@example.com -e ENTITY_NAME="Company name" \ app node dist-tools/scripts/xero-connect.jsIf the Xero login offers several organisations and the name does not pick one, add
-e TENANT_ID=<tenant id>(scripts/xero-connect.tsprints the ids it sees).The script prints a Xero consent URL. Open it in the browser on the laptop, sign in to Xero and allow access to the one organisation. Xero sends the browser to
http://localhost:8734/callback, which the SSH forward carries to the container. The page says "Connected. You can close this tab." The script printsSaved the connection for entity ... -> tenant ...and exits. An error such as a non-GBP organisation means nothing was saved (ADR 0025).Only if a statement-file account must be set up again, run
dist-tools/scripts/statement-account-add.jsthe same way, with-e XERO_BANK_ACCOUNT_NAME="Account name in Xero"added and no-p(it needs no callback). Reconnecting Xero does not remove existing accounts.Leave the root shell and close the SSH session, which closes the forward. Close the window.
Check it worked
In Claude, call connection_check for the company. It must say the company is connected and Xero is reachable. Then run any read-only tool, for example bank_accounts_list. If connection_check still says to reconnect, repeat from step 3, and check the redirect URI and the operator's access.
Never
- Never copy tokens,
xero_connectionrows,XERO_TOKEN_ENCRYPTION_KEY, the release.envor a database dump off the NAS to make this work. - Never run
xero-connectfrom a laptop against production (Dopplerprdor the NAS database). Laptops use Dopplerdevand the Demo Company database only (ADR 0030,docs/dev/local-postgres-tests.md). - Never publish port 8734 beyond
127.0.0.1, and never addports:to the compose file (getmy-books-compose-checkrefuses it). - Never paste the consent URL, callback URL or any
code=value into chat or an issue. - Never reconnect a company to a different Xero organisation than the one it had without the owner's say-so.