Containers

Containers are the most common yeet payload. Catch installs them as Docker Compose services on the target host.

Yeet detects a YAML file with a top-level services: key as Docker Compose.

yeet run <svc> ./compose.yml
yeet run <svc> ./compose.yml --net=lan

Compose files should define their initial port mappings in the compose file. After deployment, use yeet service set <svc> -p HOST:CONTAINER to replace the yeet-managed published-port list for the primary service.

yeet service set <svc> -p 80:80 -p 443:443
yeet service set <svc> --publish-reset -p 443:443

If the payload looks like an OCI image reference, catch pulls it on the host and yeet generates the Compose wrapper.

yeet run <svc> nginx:latest
yeet run -p 8000:8000 <svc> ghcr.io/org/app:latest

For local images, push to the internal registry and run in one step:

yeet docker push <svc> <local-image>:<tag> --run

Dockerfile payloads are built locally for the host architecture, pushed to the internal registry, then installed on the catch host.

yeet run <svc> ./Dockerfile
yeet run -p 8000:8000 <svc> ./Dockerfile

Python and TypeScript source files are container-backed. Python runs through a uv container image, and TypeScript runs through a Deno container.

yeet run -p 8000:8000 <svc> ./server.py
yeet run -p 8000:8000 <svc> ./server.ts

For Compose services, yeet run reuses existing images unless you ask for a pull. Use --pull for a deploy-time refresh, or use the Docker commands to inspect and update image state explicitly.

yeet run <svc> ./compose.yml
yeet run --pull <svc> ./compose.yml
yeet docker outdated
yeet docker pull <svc>
yeet docker update <svc...>
yeet docker update --outdated

For Dockerfile, image, Python, and TypeScript payloads, re-run yeet run with the new payload or source file. If the service already exists in yeet.toml, yeet reuses the saved run options unless you explicitly change the payload configuration.

Container services can use ZFS-backed service roots for persistent data and yeet-managed snapshots before redeploys or Docker image updates.

yeet run <svc> ./compose.yml --service-root=tank/apps/<svc> --zfs
yeet docker update <svc>

With --zfs, --service-root is a dataset name, not a filesystem path. Catch accepts an existing dataset or creates it, then uses its mountpoint as the service root. See ZFS for snapshot defaults, retention, and service-root moves.

Use --net=lan when the service should request a LAN address. Use svc for the private service network and ts for Tailscale service netns behavior.

yeet run <svc> ./compose.yml --net=lan
yeet run <svc> ./compose.yml --net=svc,ts

See Networking for mode details. See DNS for service discovery between svc services, including how short names and *.yeet.internal names resolve inside service network namespaces.

yeet info <svc>
yeet ip <svc>
yeet logs -f <svc>
yeet restart <svc>
yeet rm <svc>

Use yeet rm --clean-data <svc> only when you also want to remove service data under the managed service root.

Docker hosts need Docker, Compose support, and the containerd snapshotter so pushed images show up locally. yeet init can install Docker on fresh Debian/Ubuntu hosts and configures the snapshotter during catch install. Docker daemon DNS remains under the host operator's control; yeet adds service discovery per workload when the service uses --net=svc. See DNS for resolver behavior, Installation for host setup, and Workflows for common update flows. ZFS is optional; see ZFS if you want dataset-backed service roots.