Day to day · Stario

Once an app is up, life with Yard is mostly pushing code. This chapter is the rest: the commands for looking around and for the occasional change.

Every command that acts on one app finds the app from the checkout you're standing in. Anywhere else, add --app heldso.

Look at the host#

yard status

One row per container: what's up, for how long, the commit it runs, its domains, and the last deploy. A few words in the table are worth knowing:

no answer: the container runs, but nothing answered an HTTP request. Usually the wrong port or 127.0.0.1.
3 restarts: Podman restarted the container. The app is crashing; read its log.
9c2c7e1 → a1b2c3d: the app runs 9c2c7e1, but the branch is at a1b2c3d. A deploy is coming, or the last one failed.

Lines that need attention are in color, and each one says which command to run next. --running hides stopped containers.

For one app in detail:

yard app status

heldso

rev 9c2c7e1 · image localhost/heldso:9c2c7e1a2b3c · trigger push

data 1.2GB · env /srv/yard/apps/heldso/env

binds

  heldso.example.com → heldso-app-1

containers

  heldso-app-1  a1b2c3d4e5f6  up 2h  2.4%  210MB

deploys

  ok  43s  2h  9c2c7e1

log

  listening on :8000

And when something feels off about the machine itself, yard status --full runs every host check and exits 1 if one fails. It's a good thing to put in a cron job.

Read logs#

yard app logs              # the app's output

yard app logs -f           # …and keep following it

yard app logs --deploy     # the last deploy, step by step

yard logs heldso-app-1     # any container, by name or id

All logs live in journald, not in the container. So you can read the log of a container that crashed and was replaced an hour ago. --since -15m, --until, and --tail 500 narrow the window.

Read events#

Logs are what apps print. Events are what happened: a container started or died, a webhook arrived, a deploy began or ended, a setting changed.

yard events --app heldso                    # one app's timeline

yard events --app heldso --event deploy.    # its deploy history

yard events -f                              # everything, live

Podman's events and Yard's events are merged into one timeline, so "the push arrived, the deploy started, the old container stopped, the new one started" reads top to bottom.

Settings#

Each app has one env file on the host, /srv/yard/apps/<name>/env.

yard env show

yard env set KEY=VALUE OTHER=VALUE

yard env unset KEY

yard env edit              # edits a copy in $EDITOR, then PUTs it back

A change reaches the container on the next deploy. Run yard app deploy to apply it right away. If the image already exists, there's no build, and Compose just recreates the container with the new values.

The file is readable only by the yard user. Values appear only through the env commands: never in yard app status, never in a log. When you change a setting, the event records the key, not the value.

Domains#

A bind connects one public name to one container. Caddy serves the name over HTTPS and proxies it to the container.

yard bind ls

yard bind set heldso.example.com                       # → heldso-app-1:8000

yard bind set www.heldso.example.com                   # a second name, same app

yard bind set api.heldso.example.com heldso-api-1:9000 # another container or port

yard bind rm www.heldso.example.com

Each name has one bind. Setting a name again replaces its bind. Caddy gets the certificate as soon as the route lands, so point the DNS at the VM first.

--try 30s tells Caddy how long to keep retrying while the container is down, before it gives up with an error. The default, 10 seconds, covers a normal container swap.

Deploy by hand#

yard app deploy

This deploys the tip of the branch the app follows, even if nothing changed. It's the way to apply new settings, or to retry after fixing something outside the repo.

Roll back#

There's no rollback command, because a rollback is a deploy of an older commit:

yard app deploy --sha 4f1e2d0

A short sha works when it matches exactly one earlier deploy. If that image is still on the host, there's no build at all, and the rollback takes seconds.

One catch: an app with the push trigger deploys the branch tip again on the next check, within five minutes. To make the rollback stick, switch the app to manual first:

yard app set --trigger manual

yard app deploy --sha 4f1e2d0

Later, yard app set --trigger push turns deploys on push back on, or you revert the bad commit and push.

Clean up#

Every deploy leaves an image behind, localhost/<name>:<sha12>. That's what makes rollbacks fast, and it also slowly fills the disk.

yard prune --dry-run       # what would go

yard prune                 # remove images no container uses, older than 7 days

yard prune --days 1

yard status shows disk use on its last line, and yard status --full breaks it down.

Remove an app#

Warning. yard app rm deletes everything the app has on the host: its containers, its clone, its env file, and its /data directory. There's no undo. Copy /srv/yard/apps/<name>/data/ first if you might want it.

yard app rm

Remove its binds with yard bind rm <host> as well.

By the way#

Every command prints a table in a terminal and JSON in a pipe. yard status | jq '.rows[].container' just works. --json and --text force one or the other.
yard <command> --help lists every flag. The CLI reference has them all on one page.
Stopped deploying a branch? yard app set --ref main moves the app to another branch. The next check deploys it.