Arcane mit Docker Compose installieren, absichern und betreiben

Arcane ist eine moderne Weboberfläche für Docker, die Container, Images, Volumes, Netzwerke und vor allem Docker-Compose-Projekte verwaltet. Dazu kommen Update-Erkennung, Schwachstellen-Scans und Sicherungen. Das Projekt getarcaneapp/arcane steht unter der BSD-3-Clause-Lizenz, hatte beim Abruf am 2. Oktober 2026 rund 7678 Sterne auf GitHub, der letzte Push stammt vom 1. Oktober 2026, das neueste Release v2.14.0 erschien am 26. September 2026.

Voraussetzungen

Arcane selbst ist schlank, die Last erzeugen die verwalteten Container.

• Linux-Server oder VM mit Docker Engine und Docker Compose v2, für einen typischen Server mit einigen Stacks mindestens 2 CPU-Kerne und 4 GB RAM
• Architektur: Die Images manager und agent gibt es laut Projekt für linux/amd64, linux/arm64, linux/arm/v7 und linux/riscv64
• Einige GB freier Speicher für Images, das Datenvolume und lokale Sicherungen
• Root- oder sudo-Zugang per SSH, weil Projektordner angelegt und Besitzrechte gesetzt werden
• Für den Betrieb mit Domain: ein Reverse Proxy mit TLS-Zertifikat, der WebSockets durchreicht
• openssl zum Erzeugen des Schlüssels

Getestet wurde mit Arcane v2.13.1 und v2.14.0 auf Debian 12 mit Docker CE.

Eckdaten	Wert
Image	ghcr.io/getarcaneapp/manager:v2.14.0
Port	3552 (HTTP, Weboberfläche und API)
Volumes	arcane-data:/app/data, Docker-Socket, Projektordner, optional /backups
Pflicht-Variablen	ENCRYPTION_KEY (32 Byte), sinnvoll APP_URL, PROJECTS_DIRECTORY, TZ
Laufzeitbenutzer	UID/GID 65532, anpassbar über PUID/PGID

Schritt 1: Projektordner und Schlüssel vorbereiten

Arcane legt neue Compose-Projekte als normale Ordner mit compose.yaml und .env auf dem Host ab. Damit Arcane und der Docker-Daemon relative Pfade wie ./config gleich auflösen, muss der Projektordner innen und außen unter demselben absoluten Pfad liegen. Das Image startet als root, wechselt danach aber auf den Benutzer 65532. Der Ordner muss diesem Benutzer gehören, sonst scheitert das Anlegen von Projekten (siehe Typische Fehler).

sudo mkdir -p /opt/arcane/stack /opt/arcane/projects /opt/arcane/backups
sudo chown 65532:65532 /opt/arcane/projects /opt/arcane/backups
cd /opt/arcane/stack
openssl rand -hex 32

Der ausgegebene Hex-Wert ist Ihr ENCRYPTION_KEY. Arcane verschlüsselt damit gespeicherte Geheimnisse wie Registry-Token. Legen Sie ihn zusätzlich in Ihrem Passwortmanager ab.

Verifizieren: ls -ld /opt/arcane/projects zeigt als Besitzer 65532 65532, und Sie haben einen 64 Zeichen langen Hex-Schlüssel notiert.

Schritt 2: compose.yaml und .env anlegen

Basis ist das offizielle Beispiel compose.basic.yaml, ergänzt um einen gepinnten Tag, eine Zeitzone für geplante Jobs und einen festen Volumenamen für einfache Sicherungen.

services:
  arcane:
    image: ghcr.io/getarcaneapp/manager:${ARCANE_TAG}
    container_name: arcane
    ports:
      - "3552:3552"
    volumes:
      # Vollzugriff auf Docker, entspricht Root auf dem Host
      - /var/run/docker.sock:/var/run/docker.sock
      # Datenbank, Einstellungen, verschlüsselte Zugangsdaten
      - arcane-data:/app/data
      # Projektordner: innen und außen derselbe absolute Pfad
      - /opt/arcane/projects:/opt/arcane/projects
      # Ablage für Arcane-eigene Sicherungen
      - /opt/arcane/backups:/backups
    environment:
      - APP_URL=${APP_URL}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - PROJECTS_DIRECTORY=/opt/arcane/projects
      - TZ=Europe/Berlin
    cgroup: host
    healthcheck:
      test: ["CMD", "./arcane", "health", "--timeout", "2s"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 15s
    restart: unless-stopped

volumes:
  arcane-data:
    name: arcane-data

# Version fest vorgeben, GHCR-Tags tragen das v-Präfix
ARCANE_TAG=v2.14.0
# Adresse, unter der Arcane erreichbar ist
APP_URL=https://arcane.example.de
# 32 Byte, erzeugt mit: openssl rand -hex 32
ENCRYPTION_KEY=HIER_DEN_ERZEUGTEN_SCHLUESSEL_EINTRAGEN

Ein JWT_SECRET brauchen Sie nicht mehr. Arcane signiert Sitzungen laut Dokumentation mit einem selbst erzeugten Schlüssel. ANALYTICS_DISABLED=true schaltet den Heartbeat ab, der Version und eine zufällige Instanz-ID meldet. Schützen Sie die .env mit chmod 600 .env.

Verifizieren: docker compose config gibt die Konfiguration ohne Fehler aus und zeigt das Image ghcr.io/getarcaneapp/manager:v2.14.0.

Schritt 3: Arcane starten und Funktion prüfen

docker compose up -d
docker compose ps
docker compose logs --no-log-prefix | head -20
curl -s http://localhost:3552/api/health

Beim ersten Start migriert Arcane die Datenbank und erzeugt einen Standard-Administrator, im Log etwa Database migrations completed successfully provider=sqlite targetVersion=89 und Default admin user created!.

Verifizieren: docker compose ps zeigt Up (healthy), und der curl-Aufruf liefert "status":"UP".

Schritt 4: Erste Anmeldung und Benutzer

Öffnen Sie http://SERVER:3552 und melden Sie sich mit dem dokumentierten Standardkonto arcane und dem Passwort arcane-admin an. Arcane öffnet sofort einen Dialog, der ein neues Passwort erzwingt. Die Standardrichtlinie verlangt laut Oberfläche mindestens 12 Zeichen mit Groß- und Kleinbuchstaben, Zahl und Symbol. Bis dahin kennt jeder mit Zugriff auf Port 3552 das Passwort.

Danach sehen Sie das Dashboard mit der Umgebung Local Docker, die Arcane über unix:///var/run/docker.sock anspricht. Legen Sie unter Einstellungen, Benutzer persönliche Konten an, statt das Konto arcane zu teilen. Arcane bringt Rollen, Passkeys und OIDC-Anmeldung mit.

Verifizieren: Eine Anmeldung mit arcane-admin wird nun abgelehnt. Per API kommt 401 mit Invalid username or password, das neue Passwort liefert 200.

Schritt 5: Das Sicherheitsmodell verstehen

Der Docker-Socket ist der Kern von Arcane und das größte Risiko. Wer die Docker-API bedient, startet beliebige Container und kann das Dateisystem des Hosts einhängen. Im Test genügte ein einfacher Container mit -v /etc:/host-etc:ro, um /etc/shadow des Hosts zu lesen. Arcane-Administrator ist damit gleichbedeutend mit Root auf dem Server.

Daraus folgen klare Regeln: Port 3552 nicht direkt ins Internet freigeben, sondern nur über VPN oder einen Reverse Proxy mit TLS erreichbar machen, starke Passwörter plus Passkeys aktivieren und Rechte sparsam vergeben. Ohne Anmeldung antwortet die API im Test auf /api/environments/0/containers mit 401, die Authentifizierung greift also. Das Projekt empfiehlt für gehärtete Hosts zusätzlich einen Socket-Proxy wie tecnativa/docker-socket-proxy, der nur benötigte API-Bereiche freigibt. Weil Arcane weiterhin Container erstellen muss, ersetzt das keinen Zugriffsschutz.

Am Reverse Proxy müssen laut Dokumentation WebSockets durchgereicht werden (Nginx: proxy_http_version 1.1, Header Upgrade und Connection), große Header erlaubt sein, weil die Sitzungscookies rund 5 bis 6 KB erreichen, und TRUSTED_PROXIES die Proxy-Adresse enthalten. Tragen Sie die öffentliche HTTPS-Adresse als APP_URL ein.

Verifizieren: Von außen ist nur die HTTPS-Adresse erreichbar, curl -s -o /dev/null -w '%{http_code}' https://arcane.example.de/api/environments/0/containers liefert ohne Anmeldung 401.

Schritt 6: Ein Compose-Projekt über Arcane anlegen

Unter Projekte, Neues Projekt vergeben Sie einen Namen und fügen compose.yaml und .env in die Editoren ein. Für den Test genügt ein kleiner Webserver:

services:
  web:
    image: nginx:1.29-alpine
    ports:
      - "8088:80"
    volumes:
      - web-html:/usr/share/nginx/html
    restart: unless-stopped

volumes:
  web-html:

Nach Projekt erstellen startet die Schaltfläche Hoch den Stack. Arcane schreibt die Dateien nach /opt/arcane/projects/testseite/, es bleibt also auch per Konsole bedienbar.

Verifizieren: Das Projekt zeigt den Status Running, ls /opt/arcane/projects/testseite listet compose.yaml und .env, und curl -I http://localhost:8088 antwortet mit 200.

Schritt 7: Sichern und wiederherstellen

Alles, was Arcane ausmacht, liegt im Volume arcane-data: die SQLite-Datenbank arcane.db samt WAL-Dateien, Benutzer, Einstellungen und verschlüsselte Zugangsdaten. Die Projektordner sichern Sie separat mit Ihrer üblichen Dateisicherung. Für eine konsistente Kopie stoppen Sie Arcane kurz, die verwalteten Container laufen weiter:

cd /opt/arcane/stack
docker compose stop arcane
docker run --rm -v arcane-data:/data:ro -v /opt/arcane/backups:/backup alpine \
  tar czf /backup/arcane-data-$(date +%F).tar.gz -C /data .
cp .env /opt/arcane/backups/arcane.env
docker compose start arcane

Die Kopie der .env ist Pflicht, weil sie den ENCRYPTION_KEY enthält. Kopieren Sie beides auf ein anderes System. Für die Wiederherstellung leeren Sie das Volume und spielen das Archiv zurück:

docker compose down
docker volume rm arcane-data
docker volume create arcane-data
docker run --rm -v arcane-data:/data -v /opt/arcane/backups:/backup:ro alpine \
  tar xzf /backup/arcane-data-2026-10-02.tar.gz -C /data
docker compose up -d

Im Test diente ein zusätzlich angelegtes Benutzerkonto als Marker. Auf einem frischen Volume scheiterte dessen Anmeldung mit 401, nach dem Restore klappte sie mit 200, ebenso die des Administrators.

Zusätzlich bietet Arcane unter Einstellungen, Sicherungen verschlüsselte Rustic-Snapshots, lokal oder auf S3. Sie setzen einen Wiederherstellungsschlüssel voraus, ohne den die Snapshots laut Dokumentation verloren sind.

Verifizieren: tar tzf auf das Archiv listet ./arcane.db, und nach dem Restore funktionieren alle Konten wie vorher.

Schritt 8: Update und Rollback

Arcane meldet neue Versionen im Menü. Mit gepinntem Tag aktualisieren Sie bewusst: erst sichern, dann den Tag anheben.

sed -i 's/^ARCANE_TAG=.*/ARCANE_TAG=v2.14.0/' .env
docker compose pull
docker compose up -d
docker compose logs --no-log-prefix | grep -E 'starting|migration'

Beim Sprung von v2.13.1 auf v2.14.0 meldete das Log currentVersion=87 requiredVersion=89 und führte die Migration ohne Eingriff aus, Benutzer und Projekte blieben erhalten. Der Weg zurück ist dagegen gesperrt. Setzt man den Tag einfach wieder auf v2.13.1, startet der Container in einer Neustartschleife mit database schema version 89 is newer than this Arcane binary supports (target 87 for sqlite); downgrade requires ALLOW_DOWNGRADE=true and a database backup before startup.

Der sichere Rollback besteht deshalb aus altem Tag plus Sicherung vor dem Update: Volume leeren, Archiv zurückspielen, mit v2.13.1 starten. Alternativ kann Arcane mit ALLOW_DOWNGRADE=true die Datenbank selbst zurückmigrieren, braucht dafür Internetzugang und eine vorherige Sicherung, und die Variable gehört danach wieder auf false.

Verifizieren: docker compose ps zeigt das gewünschte Image als healthy, und die erste Logzeile nennt die erwartete Version, etwa Arcane is starting... version=2.14.0.

Typische Fehler

• Projekt anlegen scheitert mit HTTP 500: Die Meldung lautet Failed to create project: failed to create project directory: create directory "/testseite": mkdirat testseite: permission denied. Der Projektordner gehört root, Arcane läuft aber als UID 65532. Abhilfe: chown 65532:65532 oder passende PUID/PGID.
• Falscher oder verlorener ENCRYPTION_KEY: Der Container startet und ist sogar healthy, die Anmeldung endet aber mit HTTP 500 und Authentication failed. Im Log steht zusätzlich Failed to decrypt registry token ... cipher: message authentication failed. Nur der Originalschlüssel aus der Sicherung hilft. Achten Sie darauf, dass Compose Recreate meldet, sonst wurde die neue .env nicht übernommen.
• Neustartschleife nach Rückschritt der Version: siehe Schritt 8, Sicherung zurückspielen statt nur den Tag zu ändern.
• Image-Tag nicht gefunden: Die Tags auf GHCR tragen das v-Präfix. v2.14.0 existiert, 2.14.0 nicht.

Häufige Fragen

Wie unterscheidet sich Arcane von Portainer und Dockge?

Dockge ist schlanker, Portainer breiter. Arcane liegt dazwischen und steht vollständig unter BSD-3-Clause.

Kann ich mehrere Docker-Hosts verwalten?

Ja. Auf weiteren Hosts läuft das Image ghcr.io/getarcaneapp/agent. Im Direct-Modus verbindet sich der Manager auf Port 3553 zum Agent, im Edge-Modus baut der Agent die Verbindung nach außen auf und braucht keinen offenen Port.

Ich habe das Admin-Passwort vergessen. Was nun?

Setzen Sie ALLOW_CLI_PASSWORD_RESET=true, erstellen Sie den Container neu und führen Sie docker exec -it arcane arcane admin reset-password aus. Entfernen Sie die Variable danach wieder.

Wie entferne ich Arcane wieder?

docker compose down -v stoppt Arcane und löscht das Volume arcane-data mit Datenbank, Benutzern und Zugangsdaten unwiderruflich. Ihre Projekte in /opt/arcane/projects und deren Container bleiben bestehen und lassen sich weiter mit docker compose betreiben. Sichern Sie vorher wie in Schritt 7.

Testumfang

Auf einem Debian-12-Testhost mit Docker CE wurden Installation, erzwungener Passwortwechsel, Anlegen und Starten eines Compose-Projekts über die Oberfläche, Backup und Restore des Datenvolumes mit Marker-Konto, falscher ENCRYPTION_KEY, Update von v2.13.1 auf v2.14.0 und Rollback über die Sicherung praktisch geprüft. Reverse-Proxy-Konfiguration, Socket-Proxy, Agents, Passkeys, OIDC, die Rustic-Sicherungen und der Passwort-Reset per CLI stammen aus der offiziellen Dokumentation.

Fazit

Arcane ist eine aufgeräumte, aktiv entwickelte Oberfläche für Teams, die ihre Stacks weiter als normale Compose-Dateien führen wollen. Die Verantwortung liegt beim Betrieb: Der Docker-Socket macht Arcane zum Root-Werkzeug, also nur hinter TLS und mit wenigen Administratoren betreiben, ENCRYPTION_KEY und Datenvolume gemeinsam sichern und vor jedem Update ein Backup ziehen, weil der Rückweg nur darüber führt.

Weiterführende Anleitungen und Quellen

• Komodo mit Docker Compose installieren und betreiben
• Dockge auf dem Synology NAS als Compose-Manager
• Portainer auf dem Synology NAS installieren
• GitHub: getarcaneapp/arcane
• Release v2.14.0
• Arcane-Dokumentation: Installation
• Arcane-Dokumentation: Socket Proxy
• Arcane-Dokumentation: Backups
• Arcane-Dokumentation: Reverse Proxy und WebSockets