# 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 noch nicht angebunden. ## 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](deploy/NATIVE_INSTALL_REQUIREMENTS.md). ## 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](https://docs.docker.com/engine/install/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. ```sh sudo ./install.sh --check sudo ./install.sh --install ``` Mit GPU-Telemetrie auf einem bereits dafür vorbereiteten Server: ```sh sudo ./install.sh --install --gpu-telemetry ``` Falls Port 8110 belegt ist, beispielsweise: ```sh 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: ```sh 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](http://127.0.0.1:8110) ö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](DEVELOPMENT.md). ## Betrieb und Updates Befehle im Checkout auf dem Debian-Server: ```sh 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. ```sh 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:` | | 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. 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](ENDPOINT.md).