Networking

How yoink reaches hosts through SSH and Tailscale, how services spread across hosts, and how yoink pf debugs a service without a published port.

Read as MarkdownEdit on GitHub

Networking in yoink has three layers:

  1. Operator → host: SSH, together with Tailscale for hostnames, auth, and ACLs.
  2. Service → service: docker networks on each host, and services[].hosts to pin a service to specific hosts.
  3. Operator → service (debugging): yoink pf <service> opens a tunnel to a container, and no host port is published.

Connectivity layer (Tailscale + SSH)

The transport of yoink is ssh://user@host. yoink opens an SSH tunnel and speaks the Docker Engine API through the Unix socket of the remote daemon. You supply the SSH connectivity layer. yoink does not decide how you reach your hosts.

We recommend Tailscale SSH for this layer, and every example in these docs assumes it. There are four reasons:

  • Hostnames work everywhere. MagicDNS gives every host a stable name (my-server) that each device on the tailnet can reach. There is no ssh_config to maintain, no jump host, and no bastion.
  • Auth without keys. Tailscale SSH issues short-lived certs from tailnet membership and ACLs. A new operator needs a tailnet invitation and an ACL grant for the tag:server group. When you revoke the tailnet membership of an operator, the access stops on every host immediately.
  • CI authentication is the same flow. A GH Actions runner with tailscale/github-action joins the tailnet as tag:ci. An ACL grants SSH from tag:ci to tag:server. yoink connects and never reads ~/.ssh/.
  • No port forwarding. The Docker daemon never listens on a TCP port. The only exposed surface is :22, and only the tailnet can reach it.

The deploy user on each host is in the docker group. That group is functionally root, so the tailnet ACLs must have a scope that fits.

What yoink owns vs leaves to the connectivity layer

concern tool
container lifecycle (pull, start, healthcheck, drain, replace) yoink
deploys in dependency order (redis before api before caddy) yoink
network isolation for each tier yoink
HTTPS, hostname routing, cert issuance yoink (bundled Caddy, see the proxy guide)
operator → host connectivity Tailscale (or your SSH config)
CI → host connectivity Tailscale (or your SSH config)
stateful services (postgres and others) yoink (with a named volume) or docker compose on the host
secrets yoink (age-sealed) or an external CLI through provider: command, see the secrets guide

Multi-host distribution

Two config keys control how services spread across hosts. replicas sets the number of containers on each host. services[].hosts sets which hosts run a service.

Default: every service on every host

By default a service runs on every host in hosts:, with replicas containers on each host.

hosts:
  - { address: prod-eu-1, user: deploy }
  - { address: prod-eu-2, user: deploy }

services:
  - name: api
    image: ghcr.io/you/api
    run:
      port: 8080
      replicas: 2

This config gives 4 api containers in total: 2 on prod-eu-1 and 2 on prod-eu-2. The rolling swap runs on each host independently. On each host, the old replicas run until every new replica passes its healthcheck.

Pinning a service to specific hosts

services[].hosts: is a whitelist of the hosts that run that service. The strings match hosts[].address.

hosts:
  - { address: prod-eu-1, user: deploy }
  - { address: prod-eu-2, user: deploy }
  - { address: prod-db-1, user: deploy }      # beefier box, dedicated to stateful

services:
  - name: api
    image: ghcr.io/you/api
    domain: api.example.com                    # bundled Caddy auto-injects on every host that runs api
    hosts: [prod-eu-1, prod-eu-2]              # public-facing tier; redis stays internal
    run: { port: 8080, replicas: 2 }

  - name: redis
    image: redis
    tag: 7-alpine
    hosts: [prod-db-1]                         # pin to the db host only
    run: { port: 6379 }

Distribute services across hosts has the config for the common shapes: horizontal scale, a singleton, a pinned stateful service, and one service for each region.

Cross-host traffic between services

yoink does not yet route traffic between services on different hosts. The default network of yoink is a docker bridge network, and a bridge network exists on one host only. Thus an api on prod-eu-1 cannot dial redis:6379 on prod-db-1 through the docker network alone.

Two patterns work today:

  • The service that dials runs on the same host as its dependency.
  • The stateful service has a publish: entry on a tailnet IP, and the consumer dials that tailnet hostname.

Docker overlay networks are a generic solution, and support for them is on the roadmap.

How yoink up schedules across hosts

For each service, yoink computes the host set: services[].hosts ∩ hosts[], or all hosts when services[].hosts is unset. yoink prepares the new containers on each host in the set, in sequence. Then it swaps one host at a time. On one host, yoink starts and probes the new replicas in sequence, then stops the old containers.

The wave order (depends_on) is global. redis completes on all its hosts before api starts, and the hosts of each service do not change this order.

Pre-deploy hooks

A pre_deploy hook runs one time. The number of replicas and the number of hosts do not multiply the hooks, so a migration runs one time. A container hook runs on the first host in hosts:.

Pruning

yoink prune examines every host independently. It removes the containers of services that the config no longer declares, and the stopped containers of the other services. It keeps a running container of a declared service, also on a host that services[].hosts no longer lists.

Port-forward

yoink pf <service> opens a tunnel from your laptop to a container port, as kubectl port-forward does. It uses the SSH connection that yoink already has to the host. The tunnel works for a service with a published host port and for a service without one. You do not publish a port to debug a service.

Why this matters

yoink does not add publish: entries by default:

  • Backend services stay on the docker network, reachable only through Caddy on :443. They are never bound to a host port.
  • Operator UIs that need direct access (pgadmin, monitoring) bind 127.0.0.1 through SSH or the tailnet, not 0.0.0.0.
  • The proxy is the only listener on :443. With origin-pull mTLS, the origin is reachable only through the edge of Cloudflare.

Debugging is the usual pressure against that default. Without pf, there are three workarounds, and each one makes the exposure or the effort worse:

  1. A “temporary” publish: entry. The line stays in the yaml permanently because its removal is a chore.
  2. docker exec and curl in the container. This works only for images that contain curl, and it gives no browser access.
  3. A one-off docker run --network=container:<target> shell with socat or nc. This is fiddly and needs a manual cleanup on each host.

yoink pf is workaround 3 in automatic form. It uses the same SSH path as the deploy, and it cleans up on Ctrl-C. The TUI opens a tunnel with one key and shows a footer band while tunnels are open. Debugging never changes what production exposes.

What it works on

yoink pf works on every service that yoink runs:

  • Services that publish a host port (pgadmin and other admin UIs).
  • Services with no publish:: the api and web shape that is secure by default.
  • Services on one network or on more than one network.
  • Services with replicas. See Replicas for the routing limits.

pf has two paths. If the service has a matching publish: entry, pf uses the published port. If not, pf starts a sidecar container that joins the docker network of the service.

Replicas

For a service with more than one replica, each connection through the tunnel can go to any healthy replica. The --host flag limits the tunnel to the replicas on one host. Sticky routing to one replica index is on the roadmap. Until then, the ↦ marker in the TUI means “this is the tunnel that I opened”. It is not a routing guarantee.

What is guaranteed

  • The same auth path as all other commands. If yoink up works against the host, yoink pf works.
  • No image dependencies on the target. pf reaches a FROM scratch image, a distroless image, and a full Debian image.
  • Nothing crosses the public internet. The tunnel is a loopback port on the host, bridged through SSH.
  • Automatic cleanup on exit. Ctrl-C, Shift-F, a TUI exit, and a crash all force-remove the sidecars and free the local port.

See also

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