AI-Profile-Router/docs/INSTALLATION.md

Saubere Installation

Diese Anleitung beschreibt den Neuaufbau. Sie löscht oder migriert keine Daten automatisch.

1. Voraussetzungen

• Debian 13 oder kompatibles Linux
• NVIDIA-Treiber und funktionierendes nvidia-smi
• Build-Werkzeuge, CMake, Git und CUDA Toolkit
• Python 3.13 für Router/FLUX und Python 3.11 für XTTS
• Docker plus Compose für Websuche
• ausreichend freier Speicher; mindestens 15 Prozent auf /

2. Benutzer und Verzeichnisse

Für produktive Dienste sollen eigene Systembenutzer verwendet werden. Der Router benötigt kontrollierte Berechtigung zum Neustart des llama.cpp-Dienstes; er sollte nicht dauerhaft als root laufen.

/opt/mike-ai/models
/opt/mike-ai/ai-profile-router
/etc/mike-ai

Geheimnisse werden mit Modus 0600 unter /etc/mike-ai abgelegt.

3. llama.cpp bauen

platform/llama/build-llama-cpp.sh checkt exakt den in platform/llama/LLAMA_CPP_COMMIT hinterlegten Commit aus. Vor einem Upgrade:

1. neuen Commit in einem separaten Build testen,
2. Standardbenchmark ausführen,
3. MCP-Grammatik und Tool Calls prüfen,
4. Commitdatei erst danach aktualisieren.

4. Modelle bereitstellen

Modelldateien werden nicht in Git gespeichert. Die erwarteten Rollen und Zielpfade stehen in platform/models/manifest.example.yaml. Für die lokale Installation wird daraus eine nicht eingecheckte manifest.local.yaml mit SHA256-Prüfsummen erstellt.

5. llama.cpp-Dienst und Profile

Die Dateien aus platform/systemd und platform/profiles installieren. Danach:

llama-profile fast

Der Befehl muss Port 8080 erst freigeben, wenn Modell und Kontext korrekt sind.

6. MCP-Konfiguration

platform/mcp/mcp-servers.example.json nach /etc/mike-ai/mcp-servers.json kopieren und nur benötigte Server aktivieren. Zugangsdaten werden ausschließlich über lokale Environment-Dateien oder einen Secret Broker referenziert.

7. Router installieren

Das bestehende deploy/install.sh installiert Router, Vision/Bild-Worker, Whisper und XTTS. Vor produktiver Verwendung müssen Modellpfade in der systemd-Datei gegen das lokale Manifest geprüft werden.

Der Installer erzeugt /etc/mike-ai/router-api-key (0600), installiert das Profilregister und legt die atomare Zustandsablage an. Danach wird der Key einmal manuell in die Secret-Stores der erlaubten Clients übernommen. Er darf nicht im Terminal-Log, in Screenshots oder in Git dokumentiert werden.

Der Router läuft aktuell als gehärteter Root-Dienst, weil er den llama.cpp-Systemdienst und temporäre GPU-Worker kontrolliert. Das ist eine bewusste Restabweichung. Ein späterer V3-Schritt soll den HTTP-Proxy als eigenen Benutzer ausführen und nur Profil-/Hotswap-Befehle an einen fest parametrisierten Root-Helper delegieren.

8. Websuche

TinySearch und SearXNG bleiben als einziges Docker-Teilsystem isoliert. Die Suchdienste sollen nur an localhost gebunden werden; nur der Web-MCP greift darauf zu.

9. Verifikation

platform/checks/verify-platform.sh kontrolliert:

• freien Plattenplatz,
• GPU und VRAM,
• aktive Dienste,
• Ports,
• Routermodelle und aktives Profil,
• llama.cpp-Health,
• unerwartete RX- und Benchmark-Dienste.

Erst nach erfolgreicher Prüfung werden Clients auf Port 8081 umgestellt.