Linux and Podman setup

On Linux, driver: auto selects k3d, which needs a container runtime. Docker works without extra setup. Fedora, RHEL, and CentOS Stream ship Podman instead, and rootless Podman needs four changes before xianyun up can start a cluster.

These steps come from the Caproni project’s Linux guide, which this book replaces. They concern Podman, systemd, and k3d, not Xianyun’s own code, and I didn’t re-run them on a Fedora host. Treat them as a starting point and check them against Podman’s own troubleshooting guide.

1. Enable the Podman socket

k3d talks to the container runtime through a socket:

$ systemctl --user enable --now podman.socket

The socket appears at /run/user/<UID>/podman/podman.sock.

2. Point the Docker CLI at it

Either create a Docker context, which leaves default alone:

$ docker context create podman --description "rootless podman" \
    --docker "host=unix:///run/user/$(id -u)/podman/podman.sock"
$ docker context use podman

or repoint the podman-docker package’s symlink, which targets the rootful socket by default. This can need repeating after system updates:

$ sudo ln -sf /run/user/$(id -u)/podman/podman.sock /var/run/docker.sock

3. Delegate the cpuset cgroup controller

k3s needs cpuset, which user sessions don’t get by default. Check:

$ cat /sys/fs/cgroup/user.slice/user-$(id -u).slice/cgroup.controllers

If cpuset is missing, add a systemd override, then log out and back in:

$ sudo mkdir -p /etc/systemd/system/user@.service.d/
$ sudo tee /etc/systemd/system/user@.service.d/delegate.conf <<'EOF'
[Service]
Delegate=cpuset cpu io memory pids
EOF
$ sudo systemctl daemon-reload

This changes which cgroup controllers user sessions can manage. It doesn’t give user processes root privileges.

4. Use unprivileged ports

Rootless Podman can’t bind ports below 1024, so map the load balancer to higher ones:

cluster:
  driver: k3d
  k3d:
    port_mappings:
      - "8080:80@loadbalancer"
      - "8443:443@loadbalancer"

Services are then at http://localhost:8080. xianyun config validate accepts this block, and config print shows the mappings unchanged.

Check it

$ systemctl --user status podman.socket
$ docker ps
$ xianyun doctor
$ xianyun up