Athena-Deck/docs/DOCKER_SERVICES.md

Docker-Laufzeit und Weitere Dienste

Decks Webserver besitzt keinen Docker-Socket. Ein kleiner, root-eigener Systemhelfer bietet über /run/athena-deck-docker/control.sock ausschließlich feste Aktionen für Status/Inventar, Docker-Erstinstallation, registrierte Videodienste und begrenzten Konfigurations-Backup/Restore. Keine freie Shell oder Docker-RPC. Unix-Dateirechte und Linux SO_PEERCRED begrenzen Clients auf root und die eingerichtete Deck-UID. Die öffentliche Deck-API verlangt eine Admin-Sitzung, POST zusätzlich den bestehenden CSRF-Schutz.

Explizite Container-Zuordnung

Nur Container mit beiden exakten Labels erscheinen unter Weitere Dienste:

services:
  studio:
    labels:
      io.athena-deck.managed: "true"
      io.athena-deck.role: "application"

docker ps -a wird bereits beim Daemon auf diese Labels gefiltert. Die normale Inventaransicht überträgt nur ID, Name, Image, Zustand und Status. Der ausdrücklich angeforderte, verschlüsselte Backup-Export sichert zusätzlich die Konfigurationen markierter Anwendungen einschließlich Secret-Dateien; Anwendungslogs und Medien bleiben ausgeschlossen. Vorhandene Container werden nicht automatisch übernommen. Labels sind eine explizite Zuordnung, keine Sicherheitsgrenze gegenüber jemandem mit eigenem Docker-Administratorzugriff.

Die erste Ansicht zeigt nur den Bestand. Ein Anwendungskatalog sowie Installation, Start/Stopp, Öffnen und Deinstallation einzelner Studios folgen separat mit anwendungsspezifischen Rezepten. Keine dekorativen, funktionslosen Aktionsknöpfe. Gewichte und Nutzerdaten werden durch diese Funktion nicht verändert.

Bestehende Docker-Testinstallation anbinden

sudo ./install.sh --docker-helper --directory /opt/athena-deck-dev/runtime

Richtet ausschließlich athena-deck-docker-helper.service ein und erneuert Deck, um das private Helfer-Socketverzeichnis einzubinden. Kein Docker-Daemon-Neustart, keine Paketinstallation. Der Helfer läuft hier mit schreibgeschütztem System und ohne Installationsrecht. Bestehendes Docker wird nur erkannt und verwendet. Neue Docker-Testinstallationen richten diese lesende Anbindung automatisch ein.

Optionales Nachinstallieren auf nativem Debian

Der native Deck-Basisinstaller muss den Helfer mit der tatsächlichen UID/GID des Deck-Service und ausdrücklich mit Installationsrecht provisionieren:

sudo python3 deploy/setup_docker_helper.py --client-uid DECK_UID --client-gid DECK_GID --allow-install

Die Flags DECK_UID/DECK_GID durch die numerischen Werte ersetzen. Der vollständige native Basisinstaller ist weiterhin noch nicht fertig; dieser Bootstrap ist separat. Anschließend bietet Einstellungen → Laufzeiten → Docker die Erstinstallation an. Vor Auslösung zeigt die GUI die konkreten Auswirkungen und verlangt die bewusste Bestätigung der Installation samt Dienst und Docker-Netzwerk-/Firewallregeln.

Unterstützt Debian 12/13, amd64/arm64. Installiert aus dem offiziellen signierten Docker-APT-Repository: docker-ce, docker-ce-cli, containerd.io, Buildx und Compose. Vorhandene Docker-/Containerd-Pakete, Konfigurationen oder Daten führen zum Abbruch vor Änderungen. Kein Entfernen von Konfliktpaketen, kein Upgrade bestehender Docker-Installationen, keine Treiberinstallation und kein Host-Reboot. NVIDIA Container Toolkit ist für GPU-Container separat erforderlich. Bereits vorhandenes Docker wird nicht über diese Oberfläche aktualisiert.

Paketinstallation läuft serverseitig weiter, wenn die Seite geschlossen wird. Kein Abbrechen mitten in dpkg; Fehler werden angezeigt, Teilinstallationen nicht blind repariert. Der Helfer muss apt und Maintainer-Skripte privilegiert ausführen; diese Berechtigung wird auf vorhandenen Athena-Installationen nicht aktiviert.

Tests decken API-Schutz, Label-Filter, verbotene Helferaktionen, feste Paketbefehle, Installationsfehler und Bestandsschutz ab. Ein echter Erstinstallationslauf auf einem frischen Debian-Host steht noch aus; auf Athena wird dafür nichts ersetzt.

API: GET /api/v1/docker, POST /api/v1/docker/install mit {"confirm": true}. Referenz: https://docs.docker.com/engine/install/debian/

Videodienste

Zusätzlich zum labelgefilterten Inventar kann der root-eigene Helfer explizit registrierte Videodienste starten und stoppen. Registrierung erfolgt einmalig in /var/lib/athena-deck-docker/video-services.json (root-eigen, 0600). Beispiel ohne Zugangsdaten:

[
  {
    "id": "ltx",
    "name": "LTX Desktop",
    "container_id": "VOLLSTAENDIGE_64_STELLIGE_DOCKER_ID",
    "api_url": "http://127.0.0.1:41955",
    "health_url": "http://127.0.0.1:41955/health",
    "token_file": "/etc/mike-ai/secrets/ltx-remote-token",
    "message": "Originale LTX-API über den vorhandenen LTX-Athena-SSH-Tunnel."
  }
]

Keine Secrets werden an Deck übertragen. Der Helfer akzeptiert nur video-status, video-start und video-stop für registrierte IDs. Container-Neuerstellung erfordert bewusste Aktualisierung der ID. Healthchecks folgen keinen Redirects. Die GUI erlaubt nur die Auswahl registrierter Dienste, keine freien Containerbefehle, Zieladressen oder Secret-Dateipfade.

Der eigenständige KI-Bereich Video speichert lediglich die aktive Laufzeit-ID. Weitere Dienste ist für separate Webfrontends vorgesehen. Ein Wechsel ist nur bei gestoppten Videodiensten möglich. Der gemeinsame Deck-API-Port reicht im Videomodus die Original-API unverändert weiter; beim Wechsel auf eine andere Engine ändert sich deren API-Vertrag. Client-Kompatibilität wird nicht übersetzt. Die Integration setzt einen vorhandenen, eingerichteten Dienst voraus; sie installiert keine beliebige Video-Engine automatisch.

Interne Verwaltungs-API: GET /api/v1/video, POST /api/v1/video/service mit { "id": "ltx" }, POST /api/v1/video/mode mit { "mode": "video" } oder llm. Bestehender Sitzungsschutz gilt. Start/Stop laufen asynchron und zeigen Phase sowie API-Bereitschaft.

Der zusätzliche Transport video-http ist nur über das private Unix-Socket zugänglich und an registrierte Dienst-IDs gebunden. Zielhost und Upstream-Zugangsdaten stammen ausschließlich aus der root-eigenen Konfiguration, niemals aus einer Client-Anfrage. Keine Redirect-Verfolgung, kein freier HTTP-Proxy. Payloads werden gestreamt und nicht protokolliert. Der öffentliche Deck-Endpunkt prüft vorher seinen Bearer-Token und den aktiven Videomodus.

Konfigurations-Backup und eingeschränkte Container-Wiederherstellung: Backup & Restore.