DEV Community

Cover image for Arcane: A Developer's Guide to the Open-Source Docker Management UI
ArshTechPro
ArshTechPro

Posted on Edited on

Arcane: A Developer's Guide to the Open-Source Docker Management UI

If you run Docker on more than one machine, you probably know the routine: SSH into a box, cd into a folder, docker compose ps, tail some logs, repeat on the next server. It works, but it does not scale well once you have a handful of hosts and a few dozen stacks.

Arcane is an open-source, self-hosted web UI for Docker and Docker Compose that tries to fix that without making you learn a new orchestration model. It sits on top of the Docker you already have and gives you a dashboard, a Compose editor, logs, a terminal, and multi-host management from one place.

This article covers what Arcane is, how to get it running, and the details that matter when you move past "it works on my laptop."

What Arcane is (and is not)

Arcane is:

  • A web UI for Docker and Compose. Containers, images, volumes, networks, and Compose "projects" (stacks) are all first-class.
  • Self-hosted, single container. You run it next to your workloads and talk to Docker through the socket (or a socket proxy).
  • Open source under BSD-3-Clause. No paid tiers, no feature gating.
  • Built with Go and SvelteKit. The backend is Go, the frontend is SvelteKit with TypeScript.

Arcane is not:

  • An orchestrator. It does not replace Kubernetes or Swarm scheduling. It manages Docker and Compose the way you already use them.
  • A new config format. Your stacks stay as normal compose.yaml files on disk. If you stop using Arcane tomorrow, docker compose up -d still works.

That last point is the main reason a lot of developers are trying it. There is no lock-in. Arcane reads and writes standard Compose files.

Feature overview

Here is what you get out of the box:

Area What you get
Containers Start, stop, restart, inspect, real-time logs, web terminal, process list
Compose projects Create and edit stacks in the browser, deploy, pull, redeploy
Images Browse, pull, prune, browse registry repos and tags, build workspace
Networks Management plus an interactive network topology view
Multi-host Manage remote Docker hosts through agents (direct or edge mode)
GitOps Point Arcane at a Git repo and sync stacks from it
Updates Tag-based auto-updates with an optional cool-down delay
Security Trivy vulnerability scanning, image patching with Copacetic
Auth Local users, OIDC/SSO, passkeys, MFA, role mappings
Ops Scheduled volume and S3 backups, OpenTelemetry export
Automation REST API and a Go-based CLI (arcane-cli)
Runtimes Docker, plus Podman (rootful, rootless, and quadlets)

Quick start

You need Docker and Docker Compose on the host.

1. Generate an encryption key

Arcane requires a 32-byte ENCRYPTION_KEY. Either of these works:

openssl rand -hex 32
Enter fullscreen mode Exit fullscreen mode
docker run --rm ghcr.io/getarcaneapp/manager:v2 /app/arcane generate secret
Enter fullscreen mode Exit fullscreen mode

2. Create compose.yaml

services:
  arcane:
    image: ghcr.io/getarcaneapp/manager:v2
    container_name: arcane
    restart: unless-stopped
    ports:
      - "3552:3552"
    environment:
      - APP_URL=http://localhost:3552
      - ENCRYPTION_KEY=replace-with-your-generated-key
      - PROJECTS_DIRECTORY=/opt/stacks
      - TZ=UTC
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data
      - /opt/stacks:/opt/stacks

volumes:
  arcane-data:
Enter fullscreen mode Exit fullscreen mode

3. Start it

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Open http://<your-host>:3552 and log in with the default credentials:

  • Username: arcane
  • Password: arcane-admin

You will be forced to change the password on first login.

Things developers should know

The quick start gets you running. These are the details that save you time later.

1. Use the current image name and pin v2

The image moved from ghcr.io/getarcaneapp/arcane to ghcr.io/getarcaneapp/manager. Many older blog posts and templates still use the old name. Official mirrors also exist on Docker Hub (getarcaneapp/manager) and Quay (quay.io/getarcaneapp/manager).

Pin the v2 tag for anything you care about. Avoid latest and any beta tags in production.

2. Keep host and container paths identical for stacks

Notice the stacks volume above: /opt/stacks:/opt/stacks. Compose files often use relative paths for bind mounts (./data:/data). When Arcane runs docker compose from inside its container, those paths are resolved against the Docker host, not the Arcane container.

Arcane can translate mismatched paths now, but mounting the same path on both sides is still the recommended setup and avoids surprises. PROJECTS_DIRECTORY also accepts a <containerPath>:<hostPath> form if you need them to differ.

3. Mounting the Docker socket is root-equivalent

Anything with access to /var/run/docker.sock can effectively control the host. That is true for Arcane and for every other Docker UI.

For hardened setups, put a socket proxy in front of Docker and point Arcane at it:

environment:
  - DOCKER_HOST=tcp://docker-socket-proxy:2375
Enter fullscreen mode Exit fullscreen mode

Then remove the socket mount from the Arcane service. Two common proxies are wollomatic/socket-proxy (deny-by-default) and Tecnativa/docker-socket-proxy. Take the exact allow-list from Arcane's socket proxy docs rather than guessing.

One gotcha: if you use wollomatic/socket-proxy with -allowfrom, include arcane-upgrader as well as arcane. Self-upgrades run through a helper with that alias and will fail without it.

4. Every secret supports _FILE

Any sensitive variable can be read from a file by adding _FILE. This plays well with Docker secrets:

environment:
  - ENCRYPTION_KEY_FILE=/run/secrets/arcane_encryption_key
secrets:
  - arcane_encryption_key
Enter fullscreen mode Exit fullscreen mode

Also note that JWT_SECRET from older guides is no longer used in 2.x. Arcane generates and stores its own session signing key. If you still set JWT_SECRET, you just get a warning at startup, so remove it.

5. Behind a reverse proxy, set TRUSTED_PROXIES and APP_URL

If Arcane sits behind Nginx, Traefik, Caddy, or a Cloudflare Tunnel:

  • Set APP_URL to the public URL (for example https://arcane.example.com, no port).
  • Set TRUSTED_PROXIES to the CIDR of your proxy. Without it, client IPs in logs and rate limiting will be wrong.
  • Make sure WebSockets are passed through. Logs and the terminal depend on them. In Nginx that means proxy_http_version 1.1 plus the Upgrade and Connection "upgrade" headers.

Minimal Nginx location block:

location / {
    proxy_pass http://127.0.0.1:3552;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
Enter fullscreen mode Exit fullscreen mode

Arcane can also serve HTTPS itself with TLS_ENABLED, TLS_CERT_FILE, and TLS_KEY_FILE if you prefer not to run a proxy.

6. Managing multiple hosts: direct vs edge agents

To manage other servers, run the Arcane agent (ghcr.io/getarcaneapp/agent) on each one. There are two modes:

  • Direct mode. The manager connects to the agent on TCP port 3553. Simple, but the agent must be reachable from the manager.
  • Edge mode. The agent dials out to the manager over mTLS. No inbound port is needed on the remote host, which makes it a good fit for machines behind NAT or a home router.

You do not need to write the agent config by hand. In the UI, go to Environments > Add Environment and Arcane generates a token and a ready-to-paste Compose snippet.

Edge agents support several transports through EDGE_TRANSPORT:

  • auto (default): gRPC tunnel with WebSocket fallback
  • grpc or websocket: force one tunnel type
  • poll: periodic check-in with no persistent tunnel, useful behind Cloudflare Tunnel or strict proxies

An agent in poll mode shows as Standby when idle. That is normal and means it is healthy.

If you run Traefik in front of the manager with edge agents on auto or grpc, disable the entrypoint read timeout, otherwise tunnels drop after about 60 seconds.

7. GitOps without a CI pipeline

You can point Arcane at a Git repository that contains your Compose files and it will keep the stacks in sync. For small teams and home labs this is often enough to get a "push to deploy" flow without setting up webhooks or a CI runner. Use SSH_KNOWN_HOSTS to pin host keys when cloning over SSH.

8. Auto-updates with a safety delay

Arcane can update containers when a new image is published for the tag you track. To reduce the risk of pulling a compromised or broken image the minute it lands, you can set an update delay in hours.

Per project, in your Compose file:

x-arcane:
  updater:
    delay: 72
Enter fullscreen mode Exit fullscreen mode

Or per container, with a label:

labels:
  - com.getarcaneapp.arcane.updater.delay=72
Enter fullscreen mode Exit fullscreen mode

A value of 0 on a service opts it out of the delay.

9. Automate it: API and CLI

Arcane exposes a REST API, and there is a Go CLI for scripting:

go install github.com/getarcaneapp/arcane/cli/v2@latest
Enter fullscreen mode Exit fullscreen mode

For automation, ADMIN_STATIC_API_KEY lets you provision a fixed API key through the environment instead of creating one in the UI.

10. Use SSO if you share it with a team

OIDC is configured under Settings > Authentication or through environment variables (OIDC_ENABLED, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL, OIDC_SCOPES). The redirect URI is:

https://<your-arcane-url>/auth/oidc/callback
Enter fullscreen mode Exit fullscreen mode

You can map IdP group claims to Arcane roles with OIDC_ROLE_MAPPINGS, including per-environment roles. If you ever lock yourself out, a local backup login is available at /login/backup.

A small but common mistake: when you use the list form of environment: in Compose, do not wrap OIDC values in quotes. The quotes become part of the value and discovery fails.

Useful environment variables

Variable Purpose Default
ENCRYPTION_KEY Required 32-byte key for encrypting stored secrets none
APP_URL Public URL of the UI http://localhost:3552
PROJECTS_DIRECTORY Where Compose projects live /app/data/projects
DOCKER_HOST Docker endpoint, use tcp:// for a socket proxy unix:///var/run/docker.sock
PUID / PGID User and group the app runs as 65532
TRUSTED_PROXIES CIDR of reverse proxies unset
DATABASE_URL Database connection SQLite
TLS_ENABLED Serve HTTPS directly false
LOG_LEVEL Log verbosity info
TZ Time zone system

If the container cannot talk to the Docker socket because of permissions, either run it as root or add the host's docker group ID with group_add.

How it compares

Arcane overlaps with tools like Portainer, Dockge, and Komodo. A rough way to think about it:

  • Portainer is the long-standing, broad option, with some features in paid editions.
  • Dockge focuses narrowly on Compose stack editing on a single host.
  • Arcane aims for a modern UI with Compose at the center, built-in multi-host agents, GitOps, security scanning, and SSO, all under a permissive open-source license with no paid tier.

The best choice depends on how many hosts you run and how much you want built in. Arcane is easy to try side by side with whatever you use now, since it works on plain Compose files.

Links:

If you try it, share your setup in the comments. I am curious how people are running it across multiple hosts.

Top comments (0)