Athena-Deck/INSTALL.md

Athena Deck: derzeitiger Docker-Testinstaller

Eigenständige Installation ohne WireGuard-Modul und ohne Änderungen am bestehenden Athena-Router. Der Installer installiert den aktuellen Deck-Anwendungsstand; Modellkatalog, Downloads und llama.cpp-Buildverwaltung sind aktiv. Das Docker-Image enthält das CUDA-Build-Toolkit; der Debian-Host wird nicht verändert. Zielprodukt bleibt ein nativer systemd-Dienst. Modellstarts sind über die angebundenen LLM-, Bild-, Sprach- und Video-Worker verfügbar.

Ziel: native Installation auf frischem Debian

Der endgültige Installer muss alle Voraussetzungen selbst einrichten können, einschließlich Python, Build-Werkzeugen, CUDA und Dienstbetrieb. Docker ist keine Voraussetzung des Zielprodukts. Der aktuelle Testinstaller erfüllt dies noch nicht. Verbindlicher Umfang und Abnahme: Native Installationsanforderungen.

Voraussetzungen des aktuellen Testinstallers

• Debian 12 oder 13, Python 3 und root/sudo.
• Docker Engine >= 28, bereits eingerichtet und erreichbar.
• Mindestens 2 GiB freier Speicher für die Anwendung, zusätzlich Platz für Docker-Images. Modelle sind nicht Teil dieser Installation.
• Freier Loopback-Port, standardmäßig 8110.
• Terminal für die Zugangseinrichtung; bei SSH ssh -t verwenden.

Auf einem frischen Server zuerst Python und Docker einrichten. Der Deck-Installer ändert bewusst weder Host-Pakete noch Docker-Daemon, Firewall-Regeln, GPU-Treiber oder Kernel. Insbesondere installiert/aktualisiert er Docker nicht automatisch auf einem bereits genutzten Server. Offizielle Anleitung: Docker Engine für Debian.

Optional für GPU-Messwerte: vorhandener NVIDIA-Treiber und vorhandenes NVIDIA Container Toolkit. --gpu-telemetry bindet ausschließlich Treiber-Capability compute,utility für Telemetrie und Fit-Prüfung ein; es installiert keinen Treiber und startet kein Modell. Ohne diese Option bleiben GPU-Werte in der Server-GUI ausdrücklich nicht verfügbar.

Installation

Den Athena-Deck-Checkout auf den Debian-Server kopieren/klonen und dort im Wurzelverzeichnis ausführen. Das Skript ist kein macOS-Installer.

sudo ./install.sh --check
sudo ./install.sh --install

Mit GPU-Telemetrie auf einem bereits dafür vorbereiteten Server:

sudo ./install.sh --install --gpu-telemetry

Falls Port 8110 belegt ist, beispielsweise:

sudo ./install.sh --check --port 8112
sudo ./install.sh --install --port 8112

--check prüft rein lesend die Voraussetzungen und testet die Port-Verfügbarkeit. Es legt weder Verzeichnisse noch Container oder Images an. Beim wirklichen Start führt Docker die endgültige Port-Kollisionsprüfung aus.

Die Installation:

1. Prüft Betriebssystem, Docker, eigenen Containernamen und Zielverzeichnis.
2. Baut ein eigenes Python-Anwendungsimage aus dem Checkout (kein llama.cpp).
3. Erstellt eine getrennte Datenablage unter /opt/athena-deck-standalone.
4. Fragt das Oberflächenkennwort zweimal verdeckt ab und fragt einen separaten API-Token ab. Leere Token-Eingabe erzeugt einen zufälligen Token.
5. Startet athena-deck-standalone und prüft die Bereitschaft.

Kein Standardkennwort. Geheimnisse werden nicht als CLI-Argumente übergeben oder in Konsolenausgaben geschrieben. Ein automatisch erzeugter API-Token liegt einmalig unter /opt/athena-deck-standalone/bootstrap/api-token.txt (0600, über das root-private Elternverzeichnis geschützt). Über einen vertraulichen Verwaltungsweg in den Passwortmanager übernehmen und anschließend diese Bootstrap-Datei entfernen. Die Anwendung selbst speichert nur Prüfwerte. Bei einem späteren Tokenwechsel wird die Bootstrap-Datei nicht erneuert; sie ist kein Token-Export.

Vorhandene Zielverzeichnisse, Zugangsdaten oder fremde Container werden nicht überschrieben. Eigene Container sind zusätzlich mit einem installationsspezifischen Docker-Label gekennzeichnet. Kein docker compose down oder globales Stoppen.

Zugriff vom Mac

Standardmäßig ist die Anwendung ausschließlich auf dem Server-Loopback erreichbar. Der Container selbst hört intern auf 8108, Docker veröffentlicht nur 127.0.0.1:8110. Kein LAN-Port und keine neue WireGuard-Verbindung.

Für Athena im Terminal auf dem Mac:

ssh -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes \
  -N -L 8110:127.0.0.1:8110 root@192.168.1.212

Danach Athena Deck öffnen und mit dem bei der Installation gewählten Kennwort anmelden. Terminal offen halten; Ctrl+C beendet nur den Tunnel. Bei anderem Installationsport beide Portangaben entsprechend anpassen. Der lokale Browserport sollte dem gewählten Serverport entsprechen (Host-Allowlist). Der Arbeitsplatz führt nur den Browser und SSH-Tunnel aus. Auch die Entwicklung läuft auf Athena; siehe DEVELOPMENT.md.

Betrieb und Updates

Befehle im Checkout auf dem Debian-Server:

sudo ./install.sh --status
sudo ./install.sh --stop
sudo ./install.sh --start

# Erst den gewünschten neuen Quellstand im Checkout bereitstellen, dann:
sudo ./install.sh --update

# Auf das zuvor gespeicherte Deck-Image zurückwechseln:
sudo ./install.sh --rollback

Updates betreffen ausschließlich den eigenen Deck-Container. Das neue Image wird vorher gebaut, der bisherige Container bleibt während des Builds in Betrieb. Vor dem Austausch wird der Zustandsordner nach backups/ kopiert. Der bisherige Container wird erst dann gestoppt und für einen Rückfall umbenannt. Scheitert der Start/Bereitschaftstest, wird der vorherige Container wiederhergestellt. Nach einem erfolgreichen Update bleibt dessen Image für --rollback erhalten. Beim Wechsel hat Deck selbst eine kurze Unterbrechung; andere Dienste werden nicht angefasst. Neue Browser-Anmeldung ist nach dem Neustart erforderlich.

Rollback wechselt die Anwendungsversion, nicht automatisch die Daten. Bei zukünftigen inkompatiblen Datenformatänderungen muss die passende gesicherte Version von state/ gezielt wiederhergestellt werden. Alte Images/Backups werden nicht automatisch gelöscht.

unless-stopped startet Deck bei einem späteren regulären Docker-/Hoststart wieder, sofern es nicht bewusst gestoppt wurde. Der Installer löst keinen solchen Neustart aus.

Für eine zweite Installation sind eigener Name, eigener Port und eigener Datenpfad nötig. Namen müssen mit athena-deck- beginnen. Bei späteren Verwaltungsbefehlen immer denselben --directory-Pfad angeben; die übrigen Betriebswerte werden aus dem Installationsmanifest gelesen.

sudo ./install.sh --install --name athena-deck-test \
  --directory /opt/athena-deck-test --port 8112
sudo ./install.sh --status --directory /opt/athena-deck-test

Abgebrochene Erstinstallation

• Vor dem Anlegen der Datenablage: Fehler beheben und --install erneut ausführen.
• Manifest vorhanden, Zugangseinrichtung noch nicht abgeschlossen: sudo ./install.sh --setup, anschließend sudo ./install.sh --start.
• Zugangsdaten vorhanden, Containerstart fehlgeschlagen: Ursache (beispielsweise belegter Port oder nicht verfügbares NVIDIA-Toolkit) beheben und --start verwenden.
• Vorhandene Daten nicht löschen oder mit einer erneuten Installation überschreiben.

Trennung und Daten

Bestandteil	Ort / Umfang
Container	athena-deck-standalone
Anwendungsimage	athena-deck-standalone:<Quellhash>
Zugangsdaten	/opt/athena-deck-standalone/state/auth.json
Installationsmanifest	/opt/athena-deck-standalone/installation.json
Bootstrap-Token	/opt/athena-deck-standalone/bootstrap/api-token.txt, nur bei Erzeugung
Zustandssicherungen	/opt/athena-deck-standalone/backups/
Für spätere Modelle reserviert	/opt/athena-deck-standalone/models/, derzeit leer

Die Webanwendung läuft als UID/GID 65534, mit schreibgeschütztem Root-Dateisystem, allen Linux-Capabilities entzogen, ohne Docker-Socket, ohne privilegierten Modus und ohne Host-Netzwerk. Ressourcenlimit: zwei CPUs, 8 GiB RAM, 128 Prozesse. GPU-Zugriff ist standardmäßig aus. Nur state/ und ein temporäres tmpfs sind für die Anwendung beschreibbar. Docker erstellt seine normalen Regeln für den neuen Container; vorhandene Gateways und ihre Konfiguration werden nicht bearbeitet.

Für das Dashboard wird Host-/proc lesend eingebunden. Wenn vorhanden, werden außerdem /data/models und /data/emergency-backups ausschließlich lesend für Dateiübersicht und Backup-Downloads eingebunden. Auf einem leeren Debian beginnen die Dashboard-Messwerte und die History neu. Eine vorhandene alte Dashboard-History kann vor dem ersten Deck-Dashboard-Start einmalig gemäß Importanleitung kopiert werden.

Die WireGuard-Einstellungen zeigen in dieser Variante „nicht angebunden“. Es gibt keinen SSH-Schlüssel im Container und keine heimliche Fernsteuerung des vorhandenen Athena-Gateways. Der bisherige WireGuard-Installer bleibt ein separater Weg und wird hier nicht aufgerufen. Eine spätere Kombination benötigt eine gezielte Erweiterung.

Browser-Profilentwürfe aus dem GUI-Prototyp liegen weiterhin im jeweiligen localStorage, nicht im Server-Zustandsordner. Sie werden nicht mitinstalliert.

Prüfstand

32 lokale Tests inklusive Fremdcontainer-Schutz, fehlgeschlagenem Update und Rückfall, Loopback-Portbindung, gesperrter SSH-Steuerung und fehlenden Zugangsdaten. Shell-/Python-Syntax geprüft. Auf Athena: lesende --check-Vorprüfung erfolgreich. Zusätzlich Image-Build und Test der echten Zugangseinrichtung mit synthetischen Testeingaben in einem kurzlebigen Container ohne Netzwerk: API-Anmeldung und Zugangsdaten nach Container-Neustart erfolgreich. Testcontainer und Test-Secrets entfernt; Startzeiten zuvor vorhandener Container unverändert.

Es wurde keine dauerhafte Installation auf Athena ausgeführt. Die interaktive Erstinstallation mit deinen echten Zugangsdaten und die optionale NVIDIA-Telemetrie sind noch nicht als persistente Installation abgenommen.

Separater Inferenz-Port

Neue Installationen veröffentlichen zusätzlich ausschließlich an Host-Loopback 8120–8124. Mit --api-ports 8120-8124 lässt sich dieser Bereich auch bei --update für eine vorhandene Deck-Installation ergänzen. Alle neuen Ports werden vor dem Update auf Kollisionen geprüft. Die GUI erlaubt den Wechsel innerhalb des Bereichs bei gestopptem Endpunkt. Nativer Betrieb kennt diese Docker-Beschränkung nicht. Betrieb, Authentifizierung und SSH-Tunnel: ENDPOINT.md.

Optionale TTS-Laufzeit

Nach der Grundinstallation wird Qwen3-TTS über Einstellungen → Laufzeiten → Text-to-Speech installiert. Der Installer liefert den Installationscode und die Versionsbindung mit; die große CUDA-Umgebung und Modellgewichte werden erst auf Klick im eigenen Deck-Zustand geladen. Voraussetzung ist ein funktionierender NVIDIA-Treiber mit GPU-Zugriff für Deck. Es werden keine System-Python-Pakete ersetzt. Aktuell wird für die Ausführung eine freie RTX 3060 vorausgesetzt.

Optionale Spracherkennung

STT verwendet die aktive llama.cpp-Laufzeit auf der CPU. Diese bei einer frischen Installation zunächst über die Build-Verwaltung erstellen und aktivieren. STT → Einrichten lädt danach das geprüfte Qwen3-ASR-Modell samt Audio-Projektor über die Downloadwarteschlange. Es sind keine zusätzlichen Python- oder CUDA-Pakete nötig. Der Installer liefert Worker und Oberfläche mit.