Add isolated Debian installer with credential setup and guarded updates
This commit is contained in:
Mikei386
+185
@@ -0,0 +1,185 @@
|
||||
# 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-Builds bleiben weiterhin GUI-Vorschau.
|
||||
|
||||
## 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
|
||||
`utility` 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).
|
||||
Die bestehende Mac-Vorschau auf Port 8108 bleibt eine separate Instanz.
|
||||
|
||||
## 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: eine CPU, 512 MiB 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.
|
||||
Reference in New Issue
Block a user