Deploy mechanics

The inputs of spec_hash, the deploy lock parameters, the secrets lookup order, the prune rules, and the container host config that yoink builds.

Read as MarkdownEdit on GitHub

spec_hash inputs

The label yoink.spec_hash holds the first 16 hex characters of the sha256 of these values. The container name uses the first 8.

Input Detail
image and tag Resolved, with your --tag overrides applied.
env map Literals, and every secrets: value as resolved at deploy time.
networks The network aliases and the set of attached networks.
labels Your labels:, the description, and the proxy fields of the service (domain, tls, the TLS secret names, a hash of caddy_extra_json).
binds As declared, before the automatic :ro rewrite.
volumes As declared.
tmpfs As declared, before the automatic noexec,nosuid,nodev rewrite.
run options memory, cpus, pids_limit, cap_drop, cap_add, security_opt, devices, read_only, init, user, restart.
ports The publish strings.
entrypoint and cmd As declared.
files: mounts The content hash of every mount.

Values not in spec_hash

Value Reason
Container name It contains the short hash, so it changes on each deploy.
yoink.deployed-by and yoink.deployed-at labels They are audit labels.
Host address The same spec runs on every applicable host.

Deploy lock

Property Value
Scope One lock for each host.
Container name yoink-deploy-lock
Image alpine:3.20
Heartbeat Every 5 seconds, the operator side runs docker exec in the sentinel to touch /tmp/heartbeat.
Expiry The sentinel exits after approximately 30 seconds without a heartbeat.
Sentinel runs on the host up stops with the error “another deploy in progress.”
Sentinel exists but is stopped yoink removes it and starts a new one.
End of up (success or error) yoink stops the heartbeat and force-removes the sentinel.
Manual release yoink lock release --yes

Log lines

Log line Meaning
lock heartbeat exec failed host=… error=…container is not running The heartbeat of your local yoink tried to touch a sentinel that a different operator removed. Your lock is gone. Close the session and open it again.

age identity lookup order

The age provider decrypts the sealed secrets.age file with one X25519 identity. yoink uses the first identity that it finds.

Priority Source Use
1 YOINK_AGE_KEY env CI
2 YOINK_AGE_KEY_FILE env Explicit override
3 ~/.config/yoink/keys/<recipient>.key Laptop default. yoink scans the directory and selects the key whose public key is in secrets.recipients:.
4 ~/.config/yoink/age.key Legacy fallback
Command Effect
yoink secrets key generate Writes a key to the keys directory (source 3).
yoink secrets key generate --print | gh secret set YOINK_AGE_KEY Sends the key to the secret store of your CI. The workflow supplies it as YOINK_AGE_KEY at deploy time.

command provider output

Property Value
Input The stdout of the command from the config.
JSON stdout that starts with {.
dotenv All other stdout (KEY=value\n).
Number of runs One for each yoink up, and one at TUI startup.
Stderr Captured. yoink shows it when the command exits non-zero.

yoink prune rules

yoink prune removes a container that has the yoink.managed=true label when one of these conditions is true:

Condition Reason in the output
Its service is not in the current config (renamed or removed). The container can be running or stopped. service not in config
Its service is in the current config and the container is not running. stale exited

yoink prune does not remove:

  • Containers without the yoink.managed=true label: legacy containers, containers that you started by hand, and the deploy lock sentinel.
  • Running containers of a service that is in the current config.
  • Images, volumes, or networks. docker volume prune and docker network prune remove volumes and networks.

The second rule also removes the previous generation that yoink rollback reads. After a prune, a rollback of that service is not possible.

yoink prune --dry-run prints the containers that match and removes nothing.

Container host config

yoink builds the docker host config from service.run.options and these fixed parts.

Part Behavior
tmpfs mount options yoink adds noexec,nosuid,nodev, unless you set exec, suid, or dev explicitly.
binds yoink adds the :ro suffix when no mode is set. :rw must be explicit.
init true by default. tini as PID 1 reaps zombies and forwards SIGTERM.
Network mode The first network in the networks: list of the service. Without that list, the first network in deploy.networks. yoink attaches the other networks before it starts the container.
Port bindings Parsed from the publish: entries.
Restart policy The restart: value (no, always, unless-stopped, on-failure). The default is unless-stopped.

Container names

Case Name
One replica <service>-<short_hash>
Replicas <service>-<short_hash>-<idx>

Healthcheck probe

Config Probe
healthcheck_path is set HTTP GET on the path.
No path is set TCP connect on port.
No port is set No probe.
healthcheck_timeout yoink tries again with a backoff until the probe passes or this time elapses.
drain_timeout The time that docker gives the old container to stop before it kills the container. yoink keeps the stopped container for yoink rollback.

See also

Type a flag, a config field, or a task.