189 lines
8.9 KiB
Markdown
189 lines
8.9 KiB
Markdown
# Athena Deck auf Debian installieren
|
|
|
|
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.
|
|
|
|
## Voraussetzungen
|
|
|
|
- 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.
|
|
|
|
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.
|