The other chapters describe the host: Podman, Caddy, the journal, the files. This one is about the program in the middle. You need it when you want to trust Yard, debug it, or change it.
One process#
Yard is one Python process, a Stario app, in the container yard-app-1. It does five things:
It answers the HTTP API that the
yardcommand calls.It hears webhooks from the forges.
It runs the check worker.
It starts deploys and follows them.
It writes the site files and asks Caddy to load them.
It keeps very little in memory: the tips from the last checks, the running deploy of each app, and the forge tokens until they expire. Everything else it reads from disk or from Podman when it needs it. So a Yard that restarts loses nothing that matters, and it never disagrees with what podman ps shows.
What happens at start#
Each time Yard starts, it:
Creates its directories under
/srv/yard, and anadmintoken on a host that has no token yet.Makes sure the
yardapp record and theyardnetwork exist.Builds the deploy image,
localhost/yard-apply, in the background. The layer cache makes this take a moment when nothing changed.Starts the check worker. Its first round of every app runs one interval later, and webhooks wake it sooner.
Loads Caddy’s config from the files on disk, retrying until Caddy answers.
Schedules the daily prune. The first run waits ten minutes, so the deploys after a boot can settle.
The API answers while those background tasks run.
The code#
The source is at github.com/stariodev/yard. It has three layers, and the imports only go one way:
app/shared.pyholds the errors, the checks on names and values, and the atomic file write. It uses only the standard library.app/cli/is theyardcommand. It also uses only the standard library: it is a thin HTTP client for the API, plus tables. It never imports the server.app/server/is the API.api.pyowns HTTP and JSON. Below it are the services (apps,sites,repos,status,doctor) and the adapters, which each wrap one outside tool (git,podman,caddy,compose,forges,journal,sources,store). Thedetectpackage holds one module per language and the templates they write.
A test enforces the direction. The CLI can be installed on any laptop with Python 3.14, and it pulls in nothing but itself.
Names#
Yard leans on names, because a name means the same thing after any restart:
<name>-app-1is the app container. Compose picks the name, and the default site file dials it.deploy-<name>is the deploy container: the lock while it runs, the record once it stops.localhost/<name>:<sha12>is the image of one commit, with-<stamp>when Yard wrote the Containerfile./srv/yard/apps/<name>/is everything the app owns on the host.
So Yard can forget everything it had in memory and still find its way around.
Yard upgrades itself#
The yard app is an app like any other, with a repo, a branch, and a trigger. The install script points it at the repo it came from, usually the public github.com/stariodev/yard, with the manual trigger. So an upgrade is one command:
yard app deploy --app yardAnd yard app set --app yard --trigger push makes each new commit on that branch upgrade the host within five minutes.
There is one twist: the deploy replaces the process that started it. Here is how that goes without falling over.
The old Yard starts
deploy-yard, the same kind of detached deploy container every app gets, and follows its log.deploy-yardbuilds the new image and runsdocker-compose upon Yard’s project. Compose replacesyard-app-1, which stops the old Yard. The log stream of youryard app deployends here, and the command says so:The log stream ended before the deploy did.deploy-yarddoes not care. It is a separate container, and it waits for the new Yard to become healthy. Yard’s healthcheck curls/healthonce a second for up to 60 seconds, so the deploy ends as soon as the new Yard answers.The new Yard reads the labels of
deploy-yard. On exit 0, they name the new revision as the one that runs, so the check does not deploy it again.A new Yard that never answers fails its healthcheck after 60 seconds.
deploy-yardstarts the old image again, and the deploy ends asreverted.
Your apps keep running the whole time. Caddy keeps running too: Compose sees that Caddy did not change and leaves it alone. Only the API is gone for the few seconds that Yard takes to start.
The record on the container is what makes this safe. Nothing needs to be written after the deploy, so it does not matter that the process which started the deploy is gone. Deploys explains the record.
To run your own fork, point the app at it: yard app set --app yard --repo https://github.com/you/yard.
Trust#
A short list of what Yard trusts, and what it does not.
Tokens. Every
/api/v1/call needsAuthorization: Bearer <token>. Yard stores each token as a SHA-256 hash in/srv/yard/tokens/, and compares hashes in constant time. The admin token also stays in plain text intokens/admin.token, mode 600, so you can recover it over SSH. Make one token per laptop withyard token new, and remove one withyard token rm. A token cannot remove itself.Webhooks. They need no token, and they grant nothing. A webhook can only ask for a check, and a check trusts only the forge. Forges and webhooks explains why.
Secrets. Env files and forge keys are mode 600. Env values leave the host only through the env routes. The journal records key names, never values.
Users. Everything runs as the unprivileged
yarduser, through rootless Podman.The deploy container is the one powerful thing. It holds the Podman socket and
/srv/yard. It runs only during a deploy, and only Yard’s own image.
Two more choices#
The whole idea names the choices that shape Yard: names instead of addresses, ask instead of trust, files instead of a database, and borrowed tools. Two more only make sense once you have seen the inside.
The record lives on the deploy container. The container already exists, and it already holds the log. With the plan in its labels, the record and the deploy can never disagree, and a Yard that restarts mid-deploy, or that the deploy replaces, loses nothing.
A refusal beats a guess. When Yard is not sure what to build, it stops and says what it found. A wrong guess that deploys costs more than a clear message that does not.
By the way#
Yard reads a few settings from its env, such as
YARD_CHECK_SECONDSandYARD_PRUNE_DAYS. Settings and data lists them.The changelog explains each release, and what changed on an upgrade.