Skip to content

Installation

Install Arcane with Docker Compose or the Linux install script.

You need Docker Engine and Docker Compose.

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

    Terminal window
    docker run --rm ghcr.io/getarcaneapp/manager:latest /app/arcane generate secret
  2. Create compose.yaml with this content:

    services:
    arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    ports:
    - "3552:3552"
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - arcane-data:/app/data
    - /opt/docker:/opt/docker
    environment:
    - ARCANE_APP_URL=http://localhost:3552
    - PUID=1000
    - PGID=1000
    - ARCANE_ENCRYPTION_KEY=<your-encryption-key>
    - ARCANE_PROJECTS_DIRECTORY=/opt/docker
    cgroup: host
    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. Keep http://localhost:3552 if you only use Arcane on the Docker host. From other devices, use http://<docker-host-ip>:3552.

  5. Set your projects folder. Replace all three /opt/docker values with the folder that holds your Compose projects. See Projects folder.

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

    Terminal window
    docker compose up -d
  7. Open Arcane at the ARCANE_APP_URL address.

  8. Sign in as arcane. Arcane generates the password on first start and writes it to /app/data/initial-admin-password. Run docker compose cp arcane:/app/data/initial-admin-password . to copy the file out.

  9. Set a new password when Arcane asks.

To choose the first admin’s username and password yourself, see Default admin account.

The dashboard after you sign in.
Arcane dashboard showing running containers, images, volumes, and host resource usage.Arcane dashboard showing running containers, images, volumes, and host resource usage.

The dashboard after you sign in.

Other ways to generate a key

Use the Arcane CLI or OpenSSL instead of a container.

The key is a passphrase of at least 32 characters. To supply an exact 32-byte key instead, prefix it with hex: or base64:.

With the Arcane CLI:

Terminal window
arcane-cli generate secret

With OpenSSL:

Terminal window
openssl rand -hex 32

Install with the Linux script instead

Installs Docker and Arcane in one command.

Terminal window
curl -fsSL https://getarcane.app/install.sh | sudo bash

To uninstall, run the interactive uninstaller. It asks whether to keep Arcane data, the Arcane user and group, and Docker:

Terminal window
curl -fsSL https://getarcane.app/uninstall.sh -o /tmp/arcane-uninstall.sh && sudo bash /tmp/arcane-uninstall.sh

To remove everything without prompting:

Terminal window
curl -fsSL https://getarcane.app/uninstall.sh | sudo bash -s -- --force --remove-all

Mount your projects folder at the same absolute path inside the container (/opt/docker, not opt/docker). Set ARCANE_PROJECTS_DIRECTORY to that path. Then:

  • Relative mounts like ./config resolve the same way for Arcane and Docker.
  • Arcane can manage projects that already exist in that folder.

Other options:

  • If you mount a different container path (such as /opt/docker:/app/data/projects), Arcane translates container paths to host paths automatically.
  • To set the mapping yourself, use ARCANE_PROJECTS_DIRECTORY=<containerPath>:<hostPath>.
  • If unset, ARCANE_PROJECTS_DIRECTORY defaults to /app/data/projects.
  • To scan more folders, mount them too and list them in ARCANE_PROJECTS_DIRECTORIES. See Additional projects directories.

The official images start as root to prepare the container, then drop to a non-root user. PUID and PGID set the host UID and GID for files Arcane creates. If omitted, they default to 65532:65532.

Mount Purpose
/var/run/docker.sock Connects Arcane to Docker. Use a socket proxy to restrict access.
arcane-data Stores Arcane’s database and application data.
Projects folder Holds your Compose projects. See Projects folder.
/builds Optional. Dockerfiles and build contexts for Image Builds.
/backups Optional. Exported volume Backups.

To use an optional folder, add it under volumes: in compose.yaml:

  • /builds: host path /srv/arcane/builds:/builds or named volume arcane-builds:/builds.
  • /backups: host path /srv/arcane/backups:/backups or named volume arcane-backups:/backups.

Declare named volumes under the top-level volumes: section too.

SELinux hosts

Use a socket proxy or relabel the Docker socket mount.

Pick one:

  • Use a socket proxy (recommended). Run a proxy, set DOCKER_HOST, and add :z to the projects mount (/opt/docker:/opt/docker:z). See Socket Proxy.
  • Mount the socket directly. Disable SELinux labeling on the Arcane container and relabel the projects mount:
services:
arcane:
image: ghcr.io/getarcaneapp/manager:latest
container_name: arcane
ports:
- "3552:3552"
security_opt:
- label:disable
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- arcane-data:/app/data
- /opt/docker:/opt/docker:z
environment:
- ARCANE_PROJECTS_DIRECTORY=/opt/docker

Container health check

Add a Docker health check with the built-in arcane health command.

arcane health checks /api/health:

services:
arcane:
image: ghcr.io/getarcaneapp/manager:latest
# ...
healthcheck:
test: ["CMD", "./arcane", "health", "--timeout", "2s"]
interval: 10s
timeout: 3s
retries: 5
start_period: 15s

start_period gives Arcane time to finish first-boot database migrations before failed checks count toward retries.

External Postgres database

Store Arcane's data in Postgres instead of the built-in SQLite file.

Set ARCANE_DATABASE_URL to use Postgres instead of the default SQLite file in arcane-data:

Terminal window
postgres://<db_username>:<db_password>@<postgres_url>:<postgres_port>/<postgres_db_name>

To switch back to SQLite, set it to:

Terminal window
file:data/arcane.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(10000)&_txlock=immediate

Supported architectures

CPU architectures for the images and binaries.

Docker pulls the matching manager or agent image for:

  • linux/amd64
  • linux/arm64
  • linux/arm/v7
  • linux/riscv64

Binaries on GitHub Releases:

Binary Linux macOS
arcane (manager), arcane-agent amd64, arm64, armv7, 386, riscv64 amd64, arm64
arcane-cli amd64, arm64, armv7, 386, riscv64 arm64 only

Preview builds

Try features that haven't been released yet.

Use the :next image tag to test unreleased builds from the main branch on a non-production instance. See Preview Builds.