capy-bearer/docs/deploy.md

Deployment pipeline

A push to main on Gitea reaches every runtime and the package repository without manual steps. The code gates run once, on the builder.

Flow

1. capy-bearer-update.timer on the builder (CT100, capy-bearer.openfu.com) runs deploy/capy-bearer-update every 5 minutes. When origin/main has a new commit, the updater builds it in a staging clone, runs the gates, installs the binaries and the site, restarts Bearer, and checks health. It then writes the revision to DEPLOYED_FILE, which nginx serves as /deployed-revision.txt.
2. The updater runs deploy/capy-bearer-distribute. For each host in DISTRIBUTE_TARGETS it streams the three runtime artifacts over SSH with DISTRIBUTE_KEY. On the target, deploy/capy-bearer-receive is the forced command of that key. It checks the application sources with the new capyc, backs up the current artifacts, installs, restarts, and checks health. A failed check or a failed health probe restores the backup. The target records the revision in bin/REVISION.
3. capy-package-release.timer on the publisher (udo-aiworker) runs deploy/capy-package-release.py every 10 minutes. When the Gitea head equals /deployed-revision.txt, no package exists for it, and the revision changes a package input, the publisher asks the packaging host (capy-bearer-dev) to run capy-package-release stage REVISION. The packaging host builds the binaries and both packages in /var/lib/capy-package-release/src and runs the package gates. The publisher copies the stage back, publishes to Arty with the worker token, fetches the published digest, and compares bytes. The publisher holds the token and has a working upload path to Arty. Evidence lands in /root/capy-package-releases/<rev>/ on both hosts.

Files

File	Installed at
deploy/capy-bearer-update	builder /usr/local/sbin/capy-bearer-update
deploy/capy-bearer-update.default	builder /etc/default/capy-bearer-update
deploy/capy-bearer-update.service, .timer	builder /etc/systemd/system/
deploy/capy-bearer-distribute	builder /usr/local/sbin/capy-bearer-distribute
deploy/capy-bearer-receive	each target /usr/local/sbin/capy-bearer-receive
deploy/capy-bearer-receive.default	each target /etc/default/capy-bearer-receive
deploy/capy-package-release.py	publisher and packaging host /usr/local/sbin/capy-package-release
deploy/capy-package-release.service, .timer	publisher /etc/systemd/system/

These files do not update themselves. Install them by hand after a change to deploy/.

Holds and rollback

• A - [ ] DEPLOY_APPROVAL: line in any docs/work/*.md file at the remote head holds the builder. Tick the box to release it.
• The builder keeps the five most recent artifact sets in /var/backups/capy-bearer/<stamp>/. A target keeps five as well. Copy the files from a backup into the runtime and restart the service to roll back.
• The package job writes failed-<rev> in its state directory after a failure and does not retry until that file is removed.

Timing

Builder: about 2.5 minutes from fetch to health. Distribution: about 30 seconds per target. Package job: about 6 minutes after the builder has finished, plus the timer interval. A revision that changes no package input gets no new package.