Skip to content

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:

  1. A company's Xero connection no longer works: the refresh token has expired or been revoked (connection_check says the stored connection no longer sees the company's organisation and to reconnect Xero; three failed refreshes also raise an alert, SPEC-008).
  2. The normal web reconnect (the Xero connect on /start and /xero, SPEC-017) is itself broken or switched off (XERO_WEB_REDIRECT_URI empty).

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/callback as a redirect URI: the script uses it unless XERO_REDIRECT_URI is 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 ​

  1. From an administrator's machine, open an SSH session to the NAS that forwards the callback port to the NAS's loopback only:

    bash
    ssh -L 8734:127.0.0.1:8734 nas

    The laptop only forwards a port and opens a browser. The script does not run on the laptop.

  2. On the NAS, as root, build the same compose command the deploy uses (infra/nas/deploy/getmy-books-up):

    bash
    sudo -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-up falls back to docker-compose if docker compose version does not work; do the same here.

  3. 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.js

    If the Xero login offers several organisations and the name does not pick one, add -e TENANT_ID=<tenant id> (scripts/xero-connect.ts prints the ids it sees).

  4. 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 prints Saved the connection for entity ... -> tenant ... and exits. An error such as a non-GBP organisation means nothing was saved (ADR 0025).

  5. Only if a statement-file account must be set up again, run dist-tools/scripts/statement-account-add.js the 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.

  6. 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_connection rows, XERO_TOKEN_ENCRYPTION_KEY, the release .env or a database dump off the NAS to make this work.
  • Never run xero-connect from a laptop against production (Doppler prd or the NAS database). Laptops use Doppler dev and the Demo Company database only (ADR 0030, docs/dev/local-postgres-tests.md).
  • Never publish port 8734 beyond 127.0.0.1, and never add ports: to the compose file (getmy-books-compose-check refuses 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.