Run Arcane on Podman

This page sets up Arcane on Podman through its Docker-compatible API socket. With a rootless user’s socket, Arcane and every container it creates stay rootless. Arcane detects Podman on its own and adds a Podman section; see Podman Overview.

Enable the Podman socket

systemctl --user enable --now podman.socket
loginctl enable-linger "$USER"

Lingering starts your user’s systemd manager at boot, without an interactive login. The socket is at /run/user/<UID>/podman/podman.sock, or %t/podman/podman.sock in a user systemd unit (%t is the user’s runtime directory).

Install Arcane

Use Compose, or a Quadlet so systemd starts Arcane at boot and restarts it if it exits.

Compose

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 (the socket inside the Podman VM) instead.

Quadlet

1. Generate the encryption key and store it as a Podman secret:

   openssl rand -hex 32 | podman secret create arcane-encryption-key -

2. Print the secret and keep a copy somewhere off this host. Without it, Arcane can’t decrypt its database if the Podman secret is ever lost.

   podman secret inspect --showsecret --format '{{.SecretData}}' arcane-encryption-key

3. Save this as ~/.config/containers/systemd/arcane.container, creating the directory if needed:

   [Unit]
   Description=Arcane Manager (rootless Podman)
   Documentation=https://getarcane.app/docs/podman/setup
   Requires=podman.socket
   After=podman.socket
   
   [Container]
   Image=ghcr.io/getarcaneapp/manager:latest
   ContainerName=arcane
   Pull=missing
   AutoUpdate=registry
   SecurityLabelDisable=true
   PodmanArgs=--cgroupns=host
   
   PublishPort=3552:3552
   Volume=%t/podman/podman.sock:/var/run/docker.sock
   Volume=arcane-data:/app/data
   Secret=arcane-encryption-key,type=mount,target=/run/secrets/arcane-key,mode=0444
   
   Environment=ARCANE_APP_URL=http://localhost:3552
   Environment=PUID=1000
   Environment=PGID=1000
   Environment=ARCANE_ENCRYPTION_KEY_FILE=/run/secrets/arcane-key
   
   HealthCmd=["./arcane","health","--timeout","2s"]
   HealthInterval=10s
   HealthTimeout=3s
   HealthRetries=5
   HealthStartPeriod=15s
   Notify=healthy
   
   [Service]
   Restart=always
   TimeoutStartSec=900
   TimeoutStopSec=70
   
   [Install]
   WantedBy=default.target

   Set ARCANE_APP_URL to your browser’s URL and PUID/PGID to your IDs (id -u, id -g). Behind a local reverse proxy, publish on 127.0.0.1:3552:3552. SecurityLabelDisable=true allows socket use on SELinux hosts, --cgroupns=host helps Arcane find its own container, and HealthCmd uses exec form because the image has no shell.

4. Start Arcane and Podman’s auto-update timer:

   systemctl --user daemon-reload
   systemctl --user start arcane.service
   systemctl --user enable --now podman-auto-update.timer

   [Install] already adds the service to default.target, so it starts at boot without enable.

To manage projects from a host folder, add a matching mount and path (see Installation):

Volume=/opt/docker:/opt/docker
Environment=ARCANE_PROJECTS_DIRECTORY=/opt/docker

Warning

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

Starting and stopping Quadlets, and Podman auto-update before 6.2, need systemd over D-Bus. Mount the bus and run Arcane as a user allowed to use it; everything else works without this.

• Rootless: mount the session bus at /run/user/<UID>/bus. keep-id maps your UID into the container unchanged, since the bus rejects subordinate IDs. Arcane starts as root, then switches to PUID/PGID to own the socket and bus.
• Rootful: units are system services only root can manage, so mount the system bus and run Arcane as root.

Rootless Compose

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>

Rootless Quadlet

Add these lines to the [Container] section of arcane.container:

User=0:0
UserNS=keep-id
Volume=%t/bus:%t/bus
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=%t/bus

Rootful Compose

services:
  arcane:
    volumes:
      - /run/podman/podman.sock:/var/run/docker.sock
      - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket
      - arcane-data:/app/data
    environment:
      - PUID=0
      - PGID=0

Run arcane-cli podman status to check the Podman version, whether Arcane runs rootless, and whether systemd is reachable. If not, the reason also shows on each Quadlet’s page and 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 there instead.

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:

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

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}}'

Expect true (rootless), every unit active, and the container healthy.

Updating Arcane

With Compose, update as on Docker. With a Quadlet, AutoUpdate=registry makes Podman check the image tag daily and restart arcane.service when it changes, rolling back if the new one isn’t healthy. Arcane’s own update action is off here, since recreating the container would take it out of systemd’s control. To check or apply now:

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

If you pin Image to a version tag, change it in the Quadlet and restart the service. Arcane’s updater also skips other Quadlet containers; update them with Podman auto-update.

Use ports 80 and 443 without root

Only root can bind ports below 1024. To let rootless containers publish HTTP and HTTPS, lower the threshold for every unprivileged user:

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.