Appearance
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.ymlon GitHub,migrate-nasanddeploy-nasrun on the self-hosted runner labelledgetmy-books-deploy, andDOPPLER_TOKEN_PRDis a secret of the GitHubproductionenvironment (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
- A
deploy-nasjob runs on main aftermigrate-nas, on the Mac mini runner that already reaches the NAS (ADR 0014). - It reads settings from Doppler
prdwith a production-only service token,DOPPLER_TOKEN_PRD, set in the runner's own environment, never in the repository. scripts/deploy-nas.shcopies 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, runsdocker compose up --build --wait, and fails unless the running app's/healthreports this commit. Amended 2026-11-03 (#79): the env file is an allow-list. It holds only the names ininfra/nas/deploy/env-allowlist(the names the compose file uses, plusCOMMIT_SHA), never the wholeprdconfig: noDATABASE_URL, deploy key or git host token. The NAS enforces the same list:getmy-books-uprefuses a release whose.envsets any other name, sets one twice, or sets aCOMPOSE_*orDOCKER_*name (ADR 0023, decision 4). A name added toprdreaches the app only once it is on the list.- Until
DOPPLER_TOKEN_PRDexists 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 failsdeploy-nasanddeploy-docsinstead, anddeploy-nasrefuses 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 optionallyNAS_DEPLOY_COMPOSE(docker-composeif 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) andCF_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.
- Deploy:
- Runner: a read-only Doppler service token for
getmy-books/prd, added asDOPPLER_TOKEN_PRDunderrunner.envsbesideDOPPLER_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 labelgetmy-books-deployand capacitymigrate-nas,deploy-nas,alert-main-failedand 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;
/healthnames 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-nasstill readsdev; moving it toprdis a follow-up onceprdis complete.