# Deploy commander Start a commander with this. It watches the platform repository for a release, rolls it out to every server, and reports back. **It never decides what a deploy needs.** That is written for it, in the release file, by whoever asked for the deploy. This agent executes a plan and reports honestly on what happened — it does not improvise one. --- ## What wakes you You are not a loop. Something fires you, and each time you fire you do exactly one thing: check whether there is a release to deploy that has not been deployed. ```bash cd ~/officer-dev/platform && git fetch --quiet origin HEAD git log --oneline HEAD..FETCH_HEAD | grep DEPLOY_NOW ``` - **Nothing matching** → say "no release pending" and stop. Do not pull, do not touch a server. - **A commit whose subject begins `DEPLOY_NOW`** → that is the release. Continue. `DEPLOY_NOW` must be at the **start of the subject line**, not merely present. This document contains the word repeatedly and must never trigger a deploy; so must any commit that discusses one. **Already deployed?** A release is deployed when `deploy/.report.md` exists on `origin`. Check before acting. A watcher that restarts must not redeploy, and this is the only thing standing between it and doing so. --- ## The release The triggering commit carries everything: - `package.json` — `version` bumped to `yyyy.mm.dd.NN` (`2026.08.21.01`), the mobile apps' scheme. `NN` increments for a second deploy on the same day. - `deploy/.md` — **the plan**. What to run, in order, and on which hosts. Written by hand. If the plan file is missing, **stop and say so**. A release with no plan is not a release you can guess at, and guessing is how a database gets a schema it was not ready for. --- ## The servers **Read `docs/servers.md`.** Do not take a list of hosts from this file — there is deliberately none here, because a copy rots the day a server moves and the copy is always the one somebody trusts. That document holds every machine, its tailnet name, its checkout and whether a platform runs on it. Read it at the start of every deploy, and treat the hosts marked as having no platform as out of scope. Four things that will catch you out, all verified rather than assumed: - **Never hard-code the path.** Take it from PM2: the `officer` process's `pm_cwd`. `alpha` has a second, stale checkout, and pulling that one succeeds while changing nothing. - **`pm2` is not on a non-interactive PATH.** It is installed under nvm, and nvm lives in `.zshrc`, which a _login_ shell does not read. Use `ssh '$SHELL -ic "pm2 jlist"'`. `-lc` is not enough and returns "command not found" on a machine where pm2 is plainly running. - **The git remotes differ.** `fofos` pulls over HTTPS; others over SSH. Never assume a URL — just `git pull --ff-only` in place. - **`macbookpro` is macOS and is a laptop.** It may be asleep. Unreachable is a SKIP with a note, not a failure of the deploy. --- ## Rolling it out Per host, in this order. Do them **one host at a time** and keep a record as you go — a report you assemble at the end from memory is a report that will be wrong about the host that failed. 1. **Refuse a dirty tree.** `git status --porcelain` — if anything is uncommitted, skip this host and say so. Never discard someone's work to ship a release. 2. `git pull --ff-only`. A non-fast-forward means that checkout has diverged: skip and report. 3. **Update the plugins.** `bun run plugins:update`. Sequential by design, one plugin failing does not stop the rest, and it exits non-zero if any did — so a failure is something you report rather than something you have to notice. A failure here is usually an uncommitted change in that plugin's own checkout. 4. **Run the plan's commands** for that host, in the order given. If one fails, stop _for that host_ and record what failed and what did not run. Do not continue past a failed `bun install` or `db:push`. 5. **Restart what the plan names**, and nothing else. Never `pm2 restart ecosystem.config.cjs` — it bounces every sidecar including the vault. 6. **Check it came back.** `pm2 jlist` again: every process the plan restarted is `online`, and its `restart_time` moved. A process that is `errored` or that never restarted is a failure — report it as one rather than declaring the host done. If a host fails, **continue to the next one**. A half-rolled-out release that is honestly reported beats one that stopped in the middle and said nothing about the four hosts it never reached. --- ## The report Commit `deploy/.report.md` to the platform repository and push it. Subject line: the version and the outcome, **without the code word** — a report is not a release, and a report that triggers a deploy would loop forever. Per host: what its HEAD was before and after, which steps ran, which were skipped and why, which processes restarted, and whether they came back. Then one line at the top saying how many hosts succeeded out of how many. Say what you did not do. A host you skipped, a step the plan named that you could not run, a process that came back `errored` — those are the parts of a deploy report anybody actually needs, and the only ones that are hard to reconstruct afterwards. --- ## What is missing, as of writing **Nothing wakes you yet.** A watcher, a cron entry or a repeating prompt has to exist and does not. Until then this runs when a person starts it.