Installation auf einem frischen Debian-Host

Der automatisierte Weg ist install.sh. Das Skript ist für Debian 12/13 amd64 gedacht, installiert Docker CE, den aktuellen Compute-only-NVIDIA-Treiber mit offenen Kernelmodulen aus dem offiziellen NVIDIA-Repository, das NVIDIA-Container-Toolkit, WireGuard, baut llama.cpp reproduzierbar, lädt Modelle mit SHA256-Prüfung und startet den Stack.

Vorher klären

Die Universität muss den ausgehenden WireGuard-Tunnel erlauben.
Heimnetz, Universitätsnetz und Docker-Netz dürfen sich nicht überschneiden.
Der WireGuard-Heim-Peer braucht eine feste öffentliche Adresse oder DNS.
Für KI-Internetzugang über zuhause: Forwarding und NAT am Heim-Peer.
Das private Repository muss auf dem neuen Host lesbar sein.

Debian installieren

Debian 13 minimal, amd64, OpenSSH-Server, kein Desktop erforderlich.
Einen normalen Administrationsbenutzer mit sudo anlegen.
Optional bei physischem Fremdzugriff: LUKS-Verschlüsselung.
BIOS: Above 4G Decoding aktiv; beide GPUs sichtbar machen.

Konfiguration

git clone <PRIVATE-REPOSITORY-URL> AI-Profile-Router
cd AI-Profile-Router
cp config/install.env.example config/install.env
chmod 600 config/install.env
editor config/install.env

Mindestens ADMIN_USER, AI_BIND_ADDRESS, WG_ADDRESS, WG_PEER_PUBLIC_KEY, WG_ENDPOINT und WG_HOME_SUBNET anpassen. Private WireGuard-, Router- und WebUI-Schlüssel werden lokal erzeugt und nur unter /etc/mike-ai gespeichert.

Installation starten

sudo ./install.sh --config config/install.env

Wenn erstmals ein NVIDIA-Treiber installiert wurde, endet das Skript bewusst mit Code 20. Dann neu starten und denselben Befehl erneut ausführen. Das Skript ist auf Wiederholung ausgelegt und löscht keine vorhandenen Modelldateien. Beim ersten Stackstart lädt der interne Piper-Container die konfigurierte deutsche Stimme in sein persistentes Volume. Dadurch kann seine erste Bereitschaft je nach Internetverbindung etwas länger dauern.

Der Installer zeigt nur den öffentlichen WireGuard-Schlüssel. Diesen am Heim-Peer eintragen:

[Peer]
PublicKey = <AUSGABE-DES-INSTALLERS>
AllowedIPs = 10.77.0.2/32

Erst wenn der Tunnel steht, kann der Bootstrap fortfahren. API-Schlüssel werden nicht ausgegeben. Sie liegen root-only unter /etc/mike-ai.

Ergebnis und Abnahme

Open WebUI: http://<WIREGUARD-IP>:8080
Router: http://<WIREGUARD-IP>:8081
llama.cpp-WebUI: absichtlich deaktiviert und nicht veröffentlicht

sudo systemctl status wg-quick@wg0 mike-ai-network-guard
sudo docker compose --env-file /etc/mike-ai/stack.env \
  -f /opt/mike-ai/stack/compose.yaml ps
curl http://<WIREGUARD-IP>:8081/health

Die TTS-Verbindung wird für eine frische Open-WebUI-Datenbank automatisch als OpenAI-kompatibler Audio-Endpunkt des Routers vorbelegt. Der Router reicht sie intern an Piper weiter; Port 8085 wird nicht am Host veröffentlicht. Ein Restore setzt zusätzlich die vier persistenten Audiofelder gezielt neu, damit alte Werte wie tts-1 oder coral die Compose-Vorgaben nicht überstimmen. Ein Ende-zu-Ende-Test ohne Ausgabe des API-Schlüssels:

set -a; source /etc/mike-ai/stack.env; set +a
curl -fsS http://127.0.0.1:8081/v1/audio/speech \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"piper","voice":"alloy","input":"Hallo von Athena.","response_format":"mp3"}' \
  -o /tmp/athena-piper-test.mp3

Zusätzlich prüfen: Uni-LAN sieht keine KI-Ports; Heimnetz erreicht beide; gestopptes WireGuard lässt KI-Container nicht ins Internet; jeder Profilwechsel startet exakt einen llama-Container; Text, Tool Call, Bild und Sprachausgabe funktionieren.

Nach dem ersten Anlegen des OpenWebUI-Administrators werden Filter, Quick Actions und die vier Arbeitsbereichsmodelle reproduzierbar eingespielt:

sudo /opt/mike-ai/stack/platform/openwebui/install-filters.sh
sudo /opt/mike-ai/stack/platform/openwebui/install-models.sh

Danach sind nur die vier benannten MikeAI-Presets sichtbar; die rohen Router-Aliase sind ausgeblendet und Medium ist die Standardauswahl. Beide Skripte sichern die OpenWebUI-Datenbank vor jeder Änderung. Der Modellinstaller synchronisiert außerdem OpenWebUIs persistente OpenAI-kompatible Verbindung mit dem internen Router und dessen aktuellem Schlüssel. Das ist erforderlich, weil persistente Providerwerte nach einer Schlüsselrotation Vorrang vor den Container-Umgebungsvariablen haben.

Werkzeug-Container

Der Installer startet Websuche automatisch in einem privaten Docker-Netz. Weitere Bereiche werden nur aktiviert, wenn ihre root-only Konfiguration schon vorhanden ist:

/etc/mike-ai/homeassistant-admin-mcp.env
/etc/mike-ai/arr-mcp.env
/etc/mike-ai/runraid/.env
/usr/local/bin/runraid                  Version 0.4.2

Nach dem Nachreichen einer Datei genügt:

sudo /opt/mike-ai/stack/platform/mcp/install-tools.sh

Auf einer frischen Open-WebUI-Datenbank werden die internen MCP-Adressen über TOOL_SERVER_CONNECTIONS vorbelegt. Bei einer übernommenen Datenbank müssen die Einträge einmal unter Admin-Einstellungen → Externe Werkzeuge geprüft oder importiert werden. Die Endpunkte stehen in platform/mcp/README.md. Kein MCP-Port wird auf dem Host veröffentlicht. Externe Clients wie Hermes benötigen später den authentifizierten WireGuard-Gateway und dürfen nicht direkt auf das interne Werkzeugnetz zugreifen.

Die Standardkonfiguration lädt IQ4-MIX für Fast und IQ4_XS Pure für Medium, Large und Ultra aus den dokumentierten Hugging-Face-Repositories. URLs, Dateinamen und SHA256 stehen vollständig in config/install.env.example. Der Installer lädt jede identische Datei nur einmal und löscht vorhandene Modelle nicht.

Open-WebUI-Daten liegen in einem Docker-Volume und müssen separat gesichert werden. Geheimnisse und Chatdaten gehören nie in Git.

5.8 KiB Raw Blame History