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.
Before you start
Section titled “Before you start”You need:
- Podman. Check with
podman --version. - A Compose provider for the Compose path: podman-compose or Docker Compose.
podman composeruns whichever one is installed. Check withpodman compose version. - The Podman socket, turned on as shown below.
Enable the Podman socket
Section titled “Enable the Podman socket”Pick rootless (recommended) or rootful.
-
Rootless. Run as the user that will own Arcane’s containers:
Terminal window systemctl --user enable --now podman.socketloginctl 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.sockin a user systemd unit (%tis the user’s runtime directory). -
Rootful. Run:
Terminal window sudo systemctl enable --now podman.socketThe socket is at
/run/podman/podman.sock.
Install Arcane
Section titled “Install Arcane”Use Compose, or a Quadlet so systemd starts Arcane at boot and restarts it if it exits.
-
Generate an encryption key. Run this and copy the output:
Terminal window podman run --rm ghcr.io/getarcaneapp/manager:latest /app/arcane generate secret -
Create
compose.yamlwith the file for your setup.Rootless (replace
<UID>and<GID>with the output ofid -uandid -g):services:arcane:image: ghcr.io/getarcaneapp/manager:latestcontainer_name: arcaneuser: "0:0"userns_mode: keep-idports:- "3552:3552"volumes:- /run/user/<UID>/podman/podman.sock:/var/run/docker.sock- arcane-data:/app/dataenvironment:- ARCANE_APP_URL=http://localhost:3552- ARCANE_ENCRYPTION_KEY=<your-encryption-key>- PUID=<UID>- PGID=<GID>security_opt:- label=disablecgroup: hosthealthcheck:test: ["CMD", "./arcane", "health", "--timeout", "2s"]interval: 10stimeout: 3sretries: 5start_period: 15srestart: unless-stoppedvolumes:arcane-data:Rootful:
services:arcane:image: ghcr.io/getarcaneapp/manager:latestcontainer_name: arcaneports:- "3552:3552"volumes:- /run/podman/podman.sock:/var/run/docker.sock- arcane-data:/app/dataenvironment:- ARCANE_APP_URL=http://localhost:3552- ARCANE_ENCRYPTION_KEY=<your-encryption-key>- PUID=0- PGID=0security_opt:- label=disablecgroup: hosthealthcheck:test: ["CMD", "./arcane", "health", "--timeout", "2s"]interval: 10stimeout: 3sretries: 5start_period: 15srestart: unless-stoppedvolumes:arcane-data: -
Paste your key. Replace
<your-encryption-key>with the key from step 1. -
Set the address. Change
ARCANE_APP_URLto the address you will open, for examplehttp://<host-ip>:3552. -
Start Arcane. In the folder with
compose.yaml, run:Terminal window podman compose up -dFor rootful, run it with
sudo. -
Open Arcane at the
ARCANE_APP_URLaddress and sign in asarcane. Arcane generates the password on first start and writes it to/app/data/initial-admin-password. Runpodman 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.
-
Generate the encryption key and store it as a Podman secret:
Terminal window openssl rand -hex 32 | podman secret create arcane-encryption-key - -
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.
Terminal window podman secret inspect --showsecret --format '{{.SecretData}}' arcane-encryption-key -
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/setupRequires=podman.socketAfter=podman.socket[Container]Image=ghcr.io/getarcaneapp/manager:latestContainerName=arcanePull=missingAutoUpdate=registrySecurityLabelDisable=truePodmanArgs=--cgroupns=hostPublishPort=3552:3552Volume=%t/podman/podman.sock:/var/run/docker.sockVolume=arcane-data:/app/dataSecret=arcane-encryption-key,type=mount,target=/run/secrets/arcane-key,mode=0444Environment=ARCANE_APP_URL=http://localhost:3552Environment=PUID=1000Environment=PGID=1000Environment=ARCANE_ENCRYPTION_KEY_FILE=/run/secrets/arcane-keyHealthCmd=["./arcane","health","--timeout","2s"]HealthInterval=10sHealthTimeout=3sHealthRetries=5HealthStartPeriod=15sNotify=healthy[Service]Restart=alwaysTimeoutStartSec=900TimeoutStopSec=70[Install]WantedBy=default.targetSet
ARCANE_APP_URLto your browser’s URL andPUID/PGIDto your IDs (id -u,id -g). Behind a local reverse proxy, publish on127.0.0.1:3552:3552.SecurityLabelDisable=trueallows socket use on SELinux hosts,--cgroupns=hosthelps Arcane find its own container, andHealthCmduses exec form because the image has no shell. -
Start Arcane and Podman’s auto-update timer:
Terminal window systemctl --user daemon-reloadsystemctl --user start arcane.servicesystemctl --user enable --now podman-auto-update.timer[Install]already adds the service todefault.target, so it starts at boot withoutenable.
To manage projects from a host folder, add a matching mount and path (see Installation):
Volume=/opt/docker:/opt/dockerEnvironment=ARCANE_PROJECTS_DIRECTORY=/opt/dockerGive Arcane access to systemd
Section titled “Give Arcane access to systemd”Only needed for starting and stopping Quadlets, and Podman auto-update before 6.2. Everything else works without it.
- Mount the systemd D-Bus socket into Arcane.
- 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-idmaps your UID into the container unchanged, since the bus rejects subordinate IDs. Arcane starts as root, then switches toPUID/PGIDto 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>Add these lines to the [Container] section of arcane.container:
User=0:0UserNS=keep-idVolume=%t/bus:%t/busEnvironment=DBUS_SESSION_BUS_ADDRESS=unix:path=%t/busservices: 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=0With 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.
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:
systemctl --user enable --now podman-restart.serviceArcane 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”Run the commands for how you installed Arcane. The health check needs about 15 seconds after start; until then it shows starting.
podman info --format '{{.Host.Security.Rootless}}'systemctl --user is-active podman.socketpodman inspect arcane --format '{{.State.Health.Status}}'Expect true, then active, then healthy.
sudo systemctl is-active podman.socketsudo podman inspect arcane --format '{{.State.Health.Status}}'Expect active, then healthy.
podman info --format '{{.Host.Security.Rootless}}'systemctl --user is-active podman.socket arcane.service podman-auto-update.timerpodman inspect arcane --format '{{.State.Health.Status}}'Expect true, then active three times, then healthy.
Updating Arcane
Section titled “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-runsystemctl --user start podman-auto-update.serviceIf 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
Section titled “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.confsudo sysctl --systemThis isn’t needed for Arcane’s own port, 3552.