224 lines
11 KiB
Markdown
224 lines
11 KiB
Markdown
# 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](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:<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](DASHBOARD.md) 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](DASHBOARD.md#bestehende-history-einmalig-übernehmen) 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](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.
|