Skip to content
SHC Docs

A podman node

A podman node runs its deployments through Podman and podman-compose. SHC needs three things of it: Podman 5 with netavark, no aardvark-dns, and podman-compose 1.5.0 or newer, the first that updates one service of a deployment without creating the others again. Debian 13 ships Podman 5 and podman-compose 1.3.0, so the compose tool comes from upstream. The Debian package only recommends Podman’s init binary, catatonit, and a service with init: true cannot start without it, so the install names it. netavark only recommends nftables and sets up every container network with nft, so the install names that too. SHC refuses a host without it with X400387FABNFT.

Install the engine on pod01, as root.

pod01
$ apt-get install -y --no-install-recommends podman catatonit netavark nftables dnsutils python3-dotenv python3-yaml
...
$ apt-get purge -y aardvark-dns
...
$ curl -fsSL https://raw.githubusercontent.com/containers/podman-compose/v1.5.0/podman_compose.py -o /usr/local/bin/podman-compose
$ chmod 0755 /usr/local/bin/podman-compose
$ podman-compose --version
...

aardvark-dns is Podman’s own resolver. On the shc fabric a container asks the node’s DNS from its own fabric address, and aardvark-dns answers from the host instead, so a podman node must not have it; SHC refuses one that does with X400398FABAVK.

Now install SHC on pod01, following Installation. The package keeps an engine a node already runs, Podman 5 included, and installs Docker only on a node with none, so pod01 gets no Docker.

explained, not walked: the learn machines have one network interface
$ ssh home01 shc node token --fields token -o text | shc node join - --name pod01 --nic eth1 --runtime podman

--nic names the interface the fabric binds when a machine has more than one; on one interface SHC picks it.

Join pod01 and say its runtime.

pod01
$ ssh home01 shc node token --fields token -o text | shc node join - --name pod01 --cloud learn --location home --runtime podman
✔ joined cluster as node "pod01" at 188.245.4.253
enabled and started podman.socket, which shcd reaches podman through

SHC reaches Podman through its API socket, which Debian ships turned off, so the join turns it on and says so.

home01
$ shc node ls --verbose
NAME ID HOST INTERNAL UNDERLAY RUNTIME CORES MEMORY FREE CORES FREE MEMORY OUTSIDE RESERVED STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD LEADER VOTER
home01 node-5571f1735b77 home01 10.192.0.1:4003 188.245.8.165 docker 2 7.6G 2.0 7.6G - - healthy ready active learn learn/home ok 0.1.0-rig.20261011014503.fa8e793e6a yes yes
pod01 node-5c73017f89a0 pod01 10.192.0.2:4003 188.245.4.253 podman 2 7.6G 2.0 7.6G - - healthy ready active learn learn/home ok 0.1.0-rig.20261011014503.fa8e793e6a no no

pod01 reads podman. For a few seconds after the join its condition reads unknown, then vault-locked until a peer hands it the vault key, within a minute, and this read waits for ready. SHC places nothing on it before then: an install that names it refuses with X409179PLCPND and installs nothing. Once its condition reads ready, install the nginx directory from the app ladder a second time, naming the runtime it needs. A deployment that names podman runs only on podman nodes, and pod01 is the only one. pod01 is also this cluster’s first join: within a minute of it home01’s daemon restarts once, as SHC promotes its database from one file into a replicated one, and a command typed on home01 in that moment can fail. Type it again.

home01
$ shc install ~/learn/nginx -s podweb --runtime podman --expose 18081=nginx:80
...

Placement puts podweb on pod01, the only node its rules, condition and capacity leave (shc inspect podweb shows why), and the render asks pod01’s own podman whether it has aardvark-dns. The leader renders for every node and starts nothing itself, so it asks no engine of its own for a deployment placed elsewhere. Port 18081 on every node forwards to podweb as port 18080 forwards to web. Read it from the engine’s side on pod01, then from a node that runs Docker. The node’s own collector, shc-collector, joins this list some minutes after the join.

pod01
$ podman ps --sort names --format '{{.Names}} {{.State}}'
master_default_traefik-forward-auth-r1_forward-auth-r1_1 running
master_default_traefik-traefik-r1_traefik-r1_1 running
prod_prod_podweb-nginx-r0_nginx-r0_1 running
...
$ curl -s http://localhost:18081/
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>
home01
$ curl -s http://localhost:18081/
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>
home01
$ shc node ls --verbose
...
$ shc ls
...

Keep pod01 for the cloud pages: a deployment’s runtime and its node’s cloud are two separate facts, and pod01 carries the first.

Next: An incus node.