Zum Hauptinhalt springen
S-EDV news
← Alle Anleitungen
📘 Anleitung Docker 02.10.2026 · 12 min Lesezeit Geprüft 15.11.2026

Arcane mit Docker Compose installieren, absichern und betreiben

Arcane verwaltet Container und Compose-Projekte im Browser. Diese getestete Anleitung zeigt Installation mit Docker Compose, sichere Erstkonfiguration, das Root-Risiko des Docker-Sockets, Backup und Restore des Datenvolumes, die Folgen eines falschen ENCRYPTION_KEY sowie Update und Rollback mit gepinntem Tag.

Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

Titelbild: Arcane mit Docker Compose, Container, Absichern, Betrieb

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, die Installation wird hier auf v3.0.0 festgeschrieben.

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; wie Sie Docker installieren, zeigt die Anleitung Docker und Docker Compose auf Linux installieren (Ubuntu/Debian)
  • 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

Als Beispiel dient ein Server mit Debian 12 und Docker CE.

EckdatenWert
Imageghcr.io/getarcaneapp/manager:v3.0.0
Port3552 (HTTP, Weboberfläche und API)
Volumesarcane-data:/app/data, Docker-Socket, Projektordner, optional /backups
Pflicht-VariablenARCANE_ENCRYPTION_KEY (32 Byte), sinnvoll ARCANE_APP_URL, ARCANE_PROJECTS_DIRECTORY, TZ
LaufzeitbenutzerUID/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.

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. Wie Healthchecks und weitere Härtungen für Compose funktionieren, erklärt die Anleitung Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb.

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:
      - ARCANE_APP_URL=${APP_URL}
      - ARCANE_ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - ARCANE_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=v3.0.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. Den Heartbeat, der laut Dokumentation Version, eine zufällige Instanz-ID und den Servertyp meldet, schalten Sie ab, indem Sie unter environment in der compose.yaml die Zeile - ARCANE_ANALYTICS_ENABLED=false ergänzen und den Container mit docker compose up -d neu erstellen. Schützen Sie die .env mit chmod 600 .env.

docker compose config gibt die Konfiguration ohne Fehler aus und zeigt das Image ghcr.io/getarcaneapp/manager:v3.0.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=115 und Default admin user created!. Das Passwort des Standardkontos erzeugt Arcane zufällig und meldet im Log Default admin password was generated and written to a file file=data/initial-admin-password.

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

Schritt 4: Erste Anmeldung und Benutzer

Arcane schreibt das Startpasswort des Standardkontos arcane in die Datei /app/data/initial-admin-password im Datenvolume. Kopieren Sie sie aus dem Container und lesen Sie das Passwort aus:

$ docker compose cp arcane:/app/data/initial-admin-password .
$ cat initial-admin-password

Öffnen Sie http://SERVER:3552 und melden Sie sich als arcane mit diesem Passwort 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 zum Wechsel beantwortet die API zum Beispiel den Abruf der Container mit 403 und password change required. Löschen Sie die kopierte Datei danach mit rm initial-admin-password.

Arcane-3.0-Dialog Standardpasswort ändern mit Feldern für aktuelles, neues und bestätigtes Passwort
Nach der ersten Anmeldung erzwingt Arcane ein neues Passwort.

Danach sehen Sie das Dashboard. Den lokalen Docker-Host führt Arcane dort unter Agenten. Legen Sie unter System, Benutzer persönliche Konten an, statt das Konto arcane zu teilen. Arcane bringt Rollen, Passkeys und OIDC-Anmeldung mit.

Arcane-3.0-Dashboard mit Agentenliste, darin der lokale Docker-Host mit Spalten für Container, Images, Updates und Risiko
Das Dashboard von Arcane 3.0 führt den lokalen Docker-Host als Agent mit Containern, Images und Updates.

Die Anmeldung mit dem neuen Passwort liefert 200, der Abruf von /api/agents/0/containers mit dem erhaltenen Token ebenfalls 200. Vor dem Passwortwechsel kam dort 403.

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. Schon ein einfacher Container mit -v /etc:/host-etc:ro genügt, 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 auf /api/agents/0/containers mit 401. 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 ARCANE_TRUSTED_PROXIES die Proxy-Adresse enthalten. Tragen Sie die öffentliche HTTPS-Adresse als APP_URL ein, sie landet über die compose.yaml in ARCANE_APP_URL.

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

Schritt 6: Ein Compose-Projekt über Arcane anlegen

Unter Projekte öffnet die Schaltfläche Projekt erstellen ein neues Projekt mit einer Vorlage für die compose.yaml im Editor. Vergeben Sie oben einen Namen, etwa testseite, und ersetzen Sie die Vorlage durch einen kleinen Webserver. Eine .env brauchen Sie nur, wenn das Projekt Variablen nutzt:

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

volumes:
  web-html:

Ein weiterer Klick auf Projekt erstellen legt das Projekt an, danach starten Sie den Stack. Arcane schreibt die compose.yaml nach /opt/arcane/projects/testseite/.

Arcane-Projektansicht testseite mit Status Running, Dateiliste mit compose.yaml und Editor
Ein über Arcane angelegtes Compose-Projekt mit nginx läuft, im Arbeitsbereich liegt die compose.yaml.

Das Projekt zeigt den Status Running, ls /opt/arcane/projects/testseite listet compose.yaml (eine leere .env legt Arcane 3.0 nicht mehr an), 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

Prüfen lässt sich das mit einem zusätzlich angelegten Benutzerkonto als Marker: Auf einem frischen Volume scheitert dessen Anmeldung mit 401, nach dem Restore klappt sie mit 200, ebenso die des Administrators.

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

Arcane-Seite System, Sicherungen mit Hinweis, zuerst einen Wiederherstellungsschlüssel einzurichten
Die eingebauten Sicherungen verlangen zuerst einen Wiederherstellungsschlüssel.

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. Setzen Sie im ersten Befehl die neue Version mit v-Präfix ein.

$ sed -i 's/^ARCANE_TAG=.*/ARCANE_TAG=vX.Y.Z/' .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.15.1 migrierte Arcane die Datenbank ohne Eingriff (currentVersion=87 requiredVersion=89), Benutzer und Projekte blieben erhalten. Zurück auf v2.13.1 startete der Container dagegen in einer Neustartschleife mit database schema version 89 is newer than this Arcane binary supports (target 87 for sqlite).

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 (ab 3.0 ARCANE_ALLOW_DOWNGRADE) die Datenbank selbst zurückmigrieren. Das setzt eine vorherige Sicherung voraus, die Variable gehört danach wieder auf false.

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

Die Updates von v2.15.1 auf v2.16.0 (Schema 90 auf 93) und von v2.16.0 auf v2.17.0 (Schema 93 auf 94) liefen mit denselben Befehlen. Datenvolume, Projektordner und ENCRYPTION_KEY bleiben dabei, sichern Sie sie vor dem Wechsel. Das geänderte Administratorpasswort blieb erhalten (bei 2.16 auch die Benutzer-ID, bei 2.17 altes Standardpasswort 401, neues 200), der Containerabruf antwortete mit Token mit 200 und ohne mit 401.

Version 2.16.0 ergänzt OpenTelemetry für Metriken, Traces und Logs und überarbeitet den multiplexierten Edge-Tunnel. Zusätzlich werden SQLite-Fremdschlüssel durchgesetzt und verwaiste Berechtigungsdatensätze entfernt. Prüfen Sie nach dem Update die Rollen Ihrer Benutzer. Hinter einem Reverse Proxy werden Client-IP-Adressen nur noch aus ausdrücklich konfigurierten TRUSTED_PROXIES (seit 3.0 ARCANE_TRUSTED_PROXIES) übernommen; tragen Sie dort die tatsächlichen Proxy-Adressen ein. Bei OIDC setzt das Zusammenführen von Konten eine verifizierte E-Mail-Adresse voraus.

Version 2.17.0 brachte laut Release Notes native Podman-Unterstützung, einen konfigurierbaren Hostnamen, eine Verzögerung vor automatischen Updates neu erschienener Images, gehärtete Authentifizierung, sicherere Wiederherstellung von Sicherungen und Änderungen am Wiederherstellungsschlüssel. Neue Pflichtvariablen gab es nicht, die offizielle Beispiel-Compose-Datei ergänzte nur stop_grace_period: 15s.

Upgrade von v2.17.0 auf v3.0.0

Laut Migrationsanleitung aktualisieren Sie zuerst auf v2.17.3, starten einmal, lösen Job-Läufe mit dem Status Needs attention auf und sichern. Arcane 3.0 liest nur noch Variablen mit dem Präfix ARCANE_. Umbenannt werden die Einträge unter environment in der compose.yaml, die .env bleibt.

$ sed -i 's/^ARCANE_TAG=.*/ARCANE_TAG=v2.17.3/' .env
$ docker compose pull
$ docker compose up -d

Nach der Sicherung wie in Schritt 7 stellen Sie um. Ersetzen Sie dabei auch ANALYTICS_DISABLED=true durch ARCANE_ANALYTICS_ENABLED=false, sonst startet Arcane 3.0 nicht:

$ sed -i -e 's/- APP_URL=/- ARCANE_APP_URL=/' -e 's/- ENCRYPTION_KEY=/- ARCANE_ENCRYPTION_KEY=/' -e 's/- PROJECTS_DIRECTORY=/- ARCANE_PROJECTS_DIRECTORY=/' compose.yaml
$ sed -i 's/^ARCANE_TAG=.*/ARCANE_TAG=v3.0.0/' .env
$ docker compose down
$ docker compose up -d

Im Test startete v3.0.0 danach als healthy, Administratorpasswort und zweiter Benutzer galten weiter (Standardpasswort 401, beide neuen Passwörter 200). Die Container-API liegt jetzt unter /api/agents/0/containers, die alte Route /api/environments/0/containers antwortet mit 404.

Mit v2.17.3 auf der Datenbank von 3.0 endete der Container im Test in einer Neustartschleife mit database schema version 115 is newer than this Arcane binary supports (target 94 for sqlite). Die Meldung schlägt ALLOW_DOWNGRADE=true vor, laut Dokumentation kann die Datenbank von 3.0 aber nicht unter die Basis von v2.17.1 zurückrollen. Spielen Sie die Sicherung von vor dem Upgrade zurück, im Test lief v2.17.3 danach wieder mit allen Konten.

Laut Release Notes bringt 3.0 außerdem ein überarbeitetes Dashboard und eine neu gestaltete Aktivitätszentrale. Benutzer, Rollen, Benachrichtigungen und Sicherungen liegen jetzt unter System, Benachrichtigungsanbieter richten Sie laut Migrationsanleitung neu ein. Cron-Zeitpläne haben nur noch fünf Felder.

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 dazu Internal Server Error method=POST path=/api/auth/login. 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. v3.0.0 existiert, 3.0.0 nicht, Docker meldet dann ghcr.io/getarcaneapp/manager:3.0.0: not found.

legacy environment variables are no longer read

Arcane 3.0 startet mit alten Variablennamen nicht und nennt jede Umbenennung, etwa rename APP_URL to ARCANE_APP_URL oder replace ANALYTICS_DISABLED=true with ARCANE_ANALYTICS_ENABLED=false. Passen Sie die compose.yaml wie in Schritt 8 an und starten Sie neu.

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. Seit Version 3.0 gibt es laut Migrationsanleitung nur noch eine Agentenart: Der Agent baut die Verbindung zum Manager selbst auf und braucht keinen offenen Port. Den direkten Modus über Port 3553 gibt es nicht mehr.

Ich habe das Admin-Passwort vergessen. Was nun?

Setzen Sie ARCANE_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.

Fazit

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

Weiterführende Anleitungen und Quellen

ArcaneDockerDocker ComposeContainer-VerwaltungSelfhostingBackup