Skip to content

0019: Deploy to the NAS from the pipeline, with production settings in Doppler prd ​

Note 2026-11-06: ADR 0046 supersedes this ADR's deploy flow host: the pipeline is now .github/workflows/ci.yml on GitHub, migrate-nas and deploy-nas run on the self-hosted runner labelled getmy-books-deploy, and DOPPLER_TOKEN_PRD is a secret of the GitHub production environment (main only) rather than a variable in the runner's environment. The rest of this ADR stands. References below to the previous host are history.

Context ​

ADR 0009 planned a deploy job; none existed. The NAS compose file gave the app no runtime settings, Doppler's prd config was empty and everything lived in dev, and nothing could publish a new version. On 2026-09-29 the Product Owner asked to publish to production and chose: a pipeline job over SSH, and production settings in Doppler prd, with dev kept for development. The web endpoint's own Access, Origin and size checks (standing rule C4) land first, since the latest version has tools that write to Xero.

Decision ​

  1. A deploy-nas job runs on main after migrate-nas, on the Mac mini runner that already reaches the NAS (ADR 0014).
  2. It reads settings from Doppler prd with a production-only service token, DOPPLER_TOKEN_PRD, set in the runner's own environment, never in the repository.
  3. scripts/deploy-nas.sh copies the checked-out commit to the NAS over SSH (deploy key and pinned host key from Doppler), writes the env file readable by the deploy user only, runs docker compose up --build --wait, and fails unless the running app's /health reports this commit. Amended 2026-11-03 (#79): the env file is an allow-list. It holds only the names in infra/nas/deploy/env-allowlist (the names the compose file uses, plus COMMIT_SHA), never the whole prd config: no DATABASE_URL, deploy key or git host token. The NAS enforces the same list: getmy-books-up refuses a release whose .env sets any other name, sets one twice, or sets a COMPOSE_* or DOCKER_* name (ADR 0023, decision 4). A name added to prd reaches the app only once it is on the list.
  4. Until DOPPLER_TOKEN_PRD exists the job skips with a warning, so main stays green while the setup below is done. Amended 2026-11-03 (#297): the setup is done, so a missing token now fails deploy-nas and deploy-docs instead, and deploy-nas refuses any commit that is not main's current head (git ls-remote origin refs/heads/main), so re-running an old job cannot deploy an older commit.

One-time setup (Product Owner) ​

  • NAS: a deploy user allowed to run Docker, with SSH enabled and a key pair made for this job. A directory for the deployment, such as /volume1/docker/getmy-books.
  • Doppler prd:
    • Deploy: NAS_DEPLOY_HOST, NAS_DEPLOY_USER, NAS_DEPLOY_DIR, NAS_DEPLOY_SSH_KEY (the private key), NAS_DEPLOY_KNOWN_HOSTS (the NAS's host key line), and optionally NAS_DEPLOY_COMPOSE (docker-compose if the plugin is missing).
    • App: APP_DB_PASSWORD, POSTGRES_PASSWORD, OWNER_EMAIL, XERO_CLIENT_ID, XERO_CLIENT_SECRET, XERO_TOKEN_ENCRYPTION_KEY, COMPANIES_HOUSE_API_KEY, GETMY_BOOKS_TUNNEL_TOKEN, CF_ACCESS_TEAM_DOMAIN (e.g. https://<team>.cloudflareaccess.com) and CF_ACCESS_AUD (the Access application's Audience tag). Added 2026-10-07 (ADR 0033): ACTIVITY_LOG_HASH_KEY, 64 hex characters (openssl rand -hex 32), the key the activity log hashes statement row IDs under. The web server refuses to start without it.
  • Runner: a read-only Doppler service token for getmy-books/prd, added as DOPPLER_TOKEN_PRD under runner.envs beside DOPPLER_TOKEN. Changed 2026-09-30 (#71, stage 1): both tokens now sit only on a dedicated runner on the Mac mini, macmini-getmy-books-deploy, registered to this repository alone with the label getmy-books-deploy and capacity
    1. migrate-nas, deploy-nas, alert-main-failed and the health check run there; the general runner holds no tokens. A pull request can still name that label in its own copy of the workflow, so write access to the repository stays limited to the Product Owner and Rob, and stage 2 (a deploy agent on the NAS that pulls from main) removes the tokens from CI altogether.

Consequences ​

  • Every merge to main deploys once the setup is done; /health names the commit (the definition of done in CLAUDE.md).
  • Statement-file bank accounts (Amex CSVs) and local files are not available to the deployed app; those tools stay local. (Attachments no longer need uploads: ADR 0031.)
  • migrate-nas still reads dev; moving it to prd is a follow-up once prd is complete.