Skip to content
Arcane

Run Arcane on Podman

Use Arcane with rootless Podman through Compose or a systemd Quadlet.

Arcane can manage Podman instead of Docker by talking to Podman’s Docker-compatible API socket. When that socket belongs to a rootless Podman user, Arcane and every container it creates stay rootless.

Arcane detects Podman on its own. Containers, images, volumes, networks, and Compose projects work as they do on Docker, and a Podman section adds pods, Quadlets, Kubernetes YAML, Podman secrets, and Podman auto-update. See Podman Overview.

Enable the Podman socket

Section titled “Enable the Podman socket”
Terminal window
systemctl --user enable --now podman.socket
loginctl enable-linger "$USER"

Lingering starts your user’s systemd manager at boot, so your user services run without an interactive login.

The socket is at /run/user/<UID>/podman/podman.sock. In a user systemd unit you can write this as %t/podman/podman.sock, where %t expands to the user’s runtime directory.

Install Arcane

Section titled “Install Arcane”

Run Arcane with Compose, or as a Quadlet so your user’s systemd manager starts it at boot and restarts it if it exits.

Follow the Installation guide, then replace the Docker socket mount with your rootless Podman socket:

services:
  arcane:
    volumes:
     - /var/run/docker.sock:/var/run/docker.sock
     - /run/user/<UID>/podman/podman.sock:/var/run/docker.sock

Replace <UID> with your numeric user ID (id -u).

On Windows 11 with Podman Desktop, mount /run/podman/podman.sock instead. It’s the socket inside the Podman VM.

The Podman socket gives Arcane control of every container owned by that Linux user. Run Arcane under a dedicated unprivileged user with no unrelated workloads or files.

Give Arcane access to systemd

Section titled “Give Arcane access to systemd”

Starting and stopping Quadlets from Arcane, and running Podman auto-update on Podman versions before 6.2, go through systemd. Arcane reaches it over D-Bus, so the bus has to be mounted into the container and Arcane has to run as a user that’s allowed to use it. Everything else works without this step.

For rootless Podman that’s the user’s session bus at /run/user/<UID>/bus. Rootless Podman normally maps container users to subordinate IDs, which the bus won’t accept, so keep-id maps your own UID into the container unchanged. Arcane starts as root inside the container and then switches to PUID/PGID, reaching the socket and the bus as their owner.

Rootful Podman’s units are system services, which only root can manage, so mount the system bus and run Arcane as root.

services:
  arcane:
    user: '0:0'
    userns_mode: keep-id
    volumes:
      - /run/user/<UID>/podman/podman.sock:/var/run/docker.sock
      - /run/user/<UID>/bus:/run/user/<UID>/bus
      - arcane-data:/app/data
    environment:
      - DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/<UID>/bus
      - PUID=<UID>
      - PGID=<GID>

Run arcane-cli podman status to check. It reports the Podman version, whether Arcane runs rootless, and whether systemd is reachable. If it isn’t, the reason also shows on each Quadlet’s page and on Podman → Auto Update.

When DOCKER_HOST points to a Podman engine on another machine, Arcane won’t use its local bus. Run an Arcane Agent on that machine instead.

Restart containers after a reboot

Section titled “Restart containers after a reboot”

A Quadlet restarts Arcane itself. To also restart the containers Arcane manages that use restart: always or restart: unless-stopped, enable Podman’s restart service:

Terminal window
systemctl --user enable --now podman-restart.service

Arcane doesn’t redeploy stopped Compose projects when it starts, so set a restart policy in each project’s Compose file.

Check that it’s working

Section titled “Check that it’s working”
Terminal window
podman info --format '{{.Host.Security.Rootless}}'
systemctl --user is-active podman.socket arcane.service podman-auto-update.timer
podman inspect arcane --format '{{.State.Health.Status}}'

The first command prints true for rootless Podman, every unit should be active, and the Arcane container should be healthy.

Updating Arcane

Section titled “Updating Arcane”

With Compose, update Arcane as you would on Docker.

With a Quadlet, Podman auto-update handles it. AutoUpdate=registry makes Podman check the image tag once a day and restart arcane.service when the image changes, rolling back if the new one doesn’t become healthy. Arcane’s own update action is turned off in this setup, because recreating the container would take it out of systemd’s control. To check for an update or apply one now:

Terminal window
podman auto-update --dry-run
systemctl --user start podman-auto-update.service

If you pin Image to a version tag, change the tag in the Quadlet and restart the service yourself.

Arcane’s updater skips the containers it finds running from Quadlets for the same reason. Update those with Podman auto-update.

Use ports 80 and 443 without root

Section titled “Use ports 80 and 443 without root”

Linux only lets root bind ports below 1024. To let rootless containers publish HTTP and HTTPS directly, lower the threshold for every unprivileged user on the host:

Terminal window
echo 'net.ipv4.ip_unprivileged_port_start=80' |
  sudo tee /etc/sysctl.d/99-rootless-ports.conf
sudo sysctl --system

This isn’t needed for Arcane’s own port, 3552.