Skip to content

Run Arcane on Podman

Run Arcane on rootless or rootful Podman with Podman Compose or a systemd Quadlet.

Arcane connects through Podman’s 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.

You need:

  • Podman. Check with podman --version.
  • A Compose provider for the Compose path: podman-compose or Docker Compose. podman compose runs whichever one is installed. Check with podman compose version.
  • The Podman socket, turned on as shown below.

Pick rootless (recommended) or rootful.

  • Rootless. Run as the user that will own Arcane’s containers:

    Terminal window
    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).

  • Rootful. Run:

    Terminal window
    sudo systemctl enable --now podman.socket

    The socket is at /run/podman/podman.sock.

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

  1. Generate an encryption key. Run this and copy the output:

    Terminal window
    podman run --rm ghcr.io/getarcaneapp/manager:latest /app/arcane generate secret
  2. Create compose.yaml with the file for your setup.

    Rootless (replace <UID> and <GID> with the output of id -u and id -g):

    services:
    arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    user: "0:0"
    userns_mode: keep-id
    ports:
    - "3552:3552"
    volumes:
    - /run/user/<UID>/podman/podman.sock:/var/run/docker.sock
    - arcane-data:/app/data
    environment:
    - ARCANE_APP_URL=http://localhost:3552
    - ARCANE_ENCRYPTION_KEY=<your-encryption-key>
    - PUID=<UID>
    - PGID=<GID>
    security_opt:
    - label=disable
    cgroup: host
    healthcheck:
    test: ["CMD", "./arcane", "health", "--timeout", "2s"]
    interval: 10s
    timeout: 3s
    retries: 5
    start_period: 15s
    restart: unless-stopped
    volumes:
    arcane-data:

    Rootful:

    services:
    arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    ports:
    - "3552:3552"
    volumes:
    - /run/podman/podman.sock:/var/run/docker.sock
    - arcane-data:/app/data
    environment:
    - ARCANE_APP_URL=http://localhost:3552
    - ARCANE_ENCRYPTION_KEY=<your-encryption-key>
    - PUID=0
    - PGID=0
    security_opt:
    - label=disable
    cgroup: host
    healthcheck:
    test: ["CMD", "./arcane", "health", "--timeout", "2s"]
    interval: 10s
    timeout: 3s
    retries: 5
    start_period: 15s
    restart: unless-stopped
    volumes:
    arcane-data:
  3. Paste your key. Replace <your-encryption-key> with the key from step 1.

  4. Set the address. Change ARCANE_APP_URL to the address you will open, for example http://<host-ip>:3552.

  5. Start Arcane. In the folder with compose.yaml, run:

    Terminal window
    podman compose up -d

    For rootful, run it with sudo.

  6. Open Arcane at the ARCANE_APP_URL address and sign in as arcane. Arcane generates the password on first start and writes it to /app/data/initial-admin-password. Run podman compose cp arcane:/app/data/initial-admin-password . to copy the file out. Set a new password when asked.

label=disable lets Arcane use the socket on SELinux hosts. cgroup: host helps Arcane find its own container. Rootless uses keep-id so Arcane starts as root, then switches to your PUID/PGID to own the socket. To manage a projects folder, add its mount and ARCANE_PROJECTS_DIRECTORY as in Installation.

On Windows 11 with Podman Desktop, use the rootful file: /run/podman/podman.sock is the socket inside the Podman VM.

Only needed for starting and stopping Quadlets, and Podman auto-update before 6.2. Everything else works without it.

  1. Mount the systemd D-Bus socket into Arcane.
  2. Run Arcane as a user allowed to use it.

Pick the example for your setup below.

  • 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.
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>

With arcane-cli installed, 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.

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.

Run the commands for how you installed Arcane. The health check needs about 15 seconds after start; until then it shows starting.

Terminal window
podman info --format '{{.Host.Security.Rootless}}'
systemctl --user is-active podman.socket
podman inspect arcane --format '{{.State.Health.Status}}'

Expect true, then active, then healthy.

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:

Terminal window
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.

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

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.