infrastructure/docs/GNAI-001-PLAN_Project-Roadmap.md

# High-Level-Implementierungsplan

**Dokumenten-ID:** GNAI-001-PLAN

**Titel:** Priorisierte Roadmap für Ghostnet.AI

**Stand:** 2026-09-24

**Status:** Arbeitsgrundlage; Entscheidungstore vor externer Veröffentlichung offen

**Referenzen:** [Projektstand](GNAI-000-DOC_Index.md), [Zielarchitektur](ai/GNAI-004-INFRA_Architecture.md), [Ansible-Plan](ai/GNAI-008-PLAN_Ansible-Deployment.md), [Modellbewertung](ai/GNAI-009-PLAN_Llama-Model-Evaluation.md), [`llama.cpp`-Sollkonfiguration](ai/GNAI-010-TECH_Llama-Serving.md)

## 1. Ziel und Planungsprinzip

Die nächste Ausbaustufe soll zuerst die bekannten externen Risiken schließen
und danach einen kleinen, reproduzierbaren LLM-Pfad von Ansible bis zur realen
Inferenz liefern. Weitere Plattformkomponenten werden erst ergänzt, wenn der
vorherige Meilenstein messbar abgenommen ist.

Jeder Meilenstein endet mit einem überprüfbaren Ergebnis. Detailaufgaben und
Befehle gehören in Rollen und SOPs; diese Roadmap enthält weder lange
Laufprotokolle noch duplizierte Sollparameter.

## 2. Kritisch überprüfte Entscheidungen

| Entscheidung | Bewertung | Konsequenz für die Roadmap |
| --- | --- | --- |
| Bekannte Sicherheitsbefunde versus sofortiger LLM-Ausbau | Eine neue Anwendung zu bauen, während öffentliche Admin- und Netzwerkgrenzen offen sind, vergrößert die Angriffsfläche und erschwert spätere Abnahmen. | Empfehlung: Sicherheitsabschluss ist Meilenstein 1. Ein rein interner LLM-Test darf nur bewusst parallelisiert werden und erzeugt noch keine öffentliche Route. |
| Privilegierter Gitea-Runner vor erster Anwendung | Der vorhandene Deployment-Schlüssel ist root-äquivalent. Veränderbarer PR-Code und Production-Secrets dürfen diese Grenze nicht teilen. Der Runner würde vor dem ersten Vertical-Slice mehr Sicherheits- als Produktnutzen erzeugen. | Zuerst lokal kontrolliert deployen. Statische CI ohne Serverzugang kann früh kommen; privilegierte Deployment-Automation erst nach stabilem Rollen- und Recovery-Verfahren. |
| LiteLLM als bereits feststehende Pflichtkomponente | `llama.cpp` stellt die interne Inferenz bereit; der Mehrwert von LiteLLM entsteht erst durch konkrete Anforderungen an individuelle API-Keys, Quoten, Policy oder Routing. Ohne diese Anforderungen ist es eine zusätzliche Betriebs- und Fehlerdomäne. | LiteLLM bleibt Zielbild-Kandidat, aber Entscheidungstor vor Meilenstein 6. Der Testing-Vertical-Slice hängt nicht davon ab. |
| 128k als erste harte Betriebsgrenze | Die VRAM-Rechnung ist plausibel, aber noch ungemessen. Ein zwingendes 128k-Ergebnis würde Modell-, ROCm- und Integrationsfehler unnötig mit Speicherdruck vermischen. | 64k ist die technische Basisabnahme; 128k bleibt das Zielprofil und wird separat freigegeben. |
| Production und Testing auf demselben Host | Konten und Stores trennen Konfiguration und Daten, nicht Kernel, Treiber oder Ausfallrisiko. Echte Hochverfügbarkeit oder sichere Host-Upgrade-Tests entstehen dadurch nicht. | Bewusst als Single-Host-Betrieb mit Wartungsfenstern führen; keine HA-Aussage treffen. Umschalt- und Recovery-Mechanismus vor Production abnehmen. |
| Zwei feste Modell-Quadlets | Die Lösung ist leicht prüfbar und vermeidet eine dynamische Verwaltungs-API, kann aber bei kopierter Konfiguration driften. | Beide Units aus einem gemeinsamen Profiltemplate rendern und den gegenseitigen Ausschluss automatisiert testen. Router-Modus erst später bewerten. |
| Encoding parallel zur Inferenz | Die Trennung der Konten verhindert keine CPU-, RAM- oder I/O-Konkurrenz. „Nur nachts“ ist allein keine Ressourcenkontrolle. | Encoding bleibt nachgelagert, bis Limits und ein gemeinsamer Lasttest vorhanden sind. |

## 3. Roadmap

### Meilenstein 0 – Prioritäten und Produktgrenze bestätigen

**Ergebnis:** Der erste Nutzerpfad und die Sicherheitsreihenfolge sind eindeutig.

- festlegen, ob Sicherheits-Meilenstein 1 den internen LLM-Test blockiert oder
  kontrolliert parallel läuft;
- erstes Produkt als API-only oder API plus Weboberfläche festlegen;
- 64k-Basis und 128k-Ziel als Abnahmemodell bestätigen;
- Verantwortliche für Review, Deployment und Sicherheitsabnahme benennen.

**Fertig, wenn:** Die vier Entscheidungen im Projektstand vermerkt sind und
kein nachfolgender Meilenstein eine stillschweigende Annahme dazu benötigt.

### Meilenstein 1 – Bestehende externe Risiken schließen

**Ergebnis:** Die aktuelle Plattform besitzt belegte Management- und
Netzwerkgrenzen, bevor weitere öffentliche Dienste hinzukommen.

- Keycloak-Adminpfad extern sperren und Vaultwarden-OIDC regressionsprüfen;
- VPN-Peers Rollen zuordnen, Per-Client-Regeln sowie Gateway-INPUT umsetzen und
  erlaubte wie verbotene Ziele aktiv testen;
- Fail2Ban-Image, Jails, kontrollierten Ban/Unban und Dienst-/LXC-Wiederanlauf
  prüfen;
- WAN- und IPv6-Exposure für Managementports erfassen;
- Ergebnisse mit Datum und Negativtests in GNAI-006/GNAI-007 dokumentieren.

**Ausführungsstand 24.09.2026:** Die externe Keycloak-Administration und die
fehlende VPN-Rollenisolierung sind live bestätigt. Die Schlüsseldateien des
WireGuard-Gateways wurden auf `0600` gehärtet. Auf CT 103 sind persönlicher und
lesender Schlüsselzugang, passwortgeschütztes sudo, SSH-Härtung,
LAN/WireGuard-Netzbaseline und der Wiederanlauf nach einem kontrollierten
Neustart abgenommen. Für die nächsten wirksamen Änderungen fehlen weiterhin
(1) ein aktueller Rückfallstand vor der Keycloak-Änderung sowie (2) die
verbindliche Rolle der beiden vorhandenen VPN-Peers. Die technische Reihenfolge
ist deshalb: Backup sichern, öffentlichen `/admin`-Pfad sperren und
regressionsprüfen, Peers zuordnen und Gateway-Regeln umsetzen, anschließend die
noch offenen Fail2Ban-Funktionstests abschließen.

**Fertig, wenn:** Die vier priorisierten Sicherheitsbefunde im zentralen Index
als bestanden oder mit ausdrücklich akzeptiertem Restrisiko dokumentiert sind.

### Meilenstein 2 – Internes LLM-Serving als Vertical-Slice

**Ergebnis:** Ein reproduzierbarer, nicht öffentlich erreichbarer
`llama.cpp`-Dienst führt reale Inferenz auf beiden GPUs aus.

- Ansible-Rolle `llama_cpp` mit validiertem Profilmanifest, atomarem Download,
  Prüfsummen, gepinntem Image, rootless Netzwerk und zwei aus einem Template
  erzeugten Quadlets implementieren;
- Image- und Modellbereitstellung vom Start beziehungsweise Profilwechsel
  trennen;
- Swift zunächst bei 64k, danach bei 128k abnehmen;
- Unsloth mit demselben technischen Verfahren abnehmen;
- Health, Modellalias, Tool-Call, Reasoning-Trennung, GPU-Verteilung,
  CPU-Offload, VRAM und Neustartverhalten protokollieren;
- zweiten identischen Ansible-Lauf mit `changed=0` nachweisen.

**Fertig, wenn:** Beide Profile die technische Abnahme aus GNAI-010 bestehen
oder ein dokumentierter Messwert eine Profilanpassung auslöst. Es existiert
weiterhin kein Host-Port und keine NPM-Route.

### Meilenstein 3 – Modellprofil auswählen

**Ergebnis:** Ein durch lokale Aufgaben belegtes Standardprofil und ein
Rollbackprofil sind festgelegt.

- kleine versionierte Testsuite mit automatischen Erwartungen und manueller
  Bewertungsrubrik erstellen;
- Swift und Unsloth zunächst mit identischen `xhigh`-Parametern vergleichen;
- anschließend Swift `xhigh` gegen Unsloth `medium` als Praxisprofile messen;
- Qualität, Tool-Zuverlässigkeit, Tokenverbrauch, Laufzeit und Ressourcen
  gemeinsam bewerten;
- MTP und Vision nur als getrennte optionale Experimente nach der Baseline
  ausführen;
- Lizenz und Nutzungsrahmen vor einer externen Freigabe bestätigen.

**Fertig, wenn:** Ein datierter Evaluierungsbericht das bevorzugte Profil,
zulässigen Kontext, Ausgabegrenze und Rollbackprofil benennt.

### Meilenstein 4 – Production- und Recovery-Fähigkeit

**Ergebnis:** Der ausgewählte interne Dienst kann kontrolliert als Production
betrieben und nach Fehlern wiederhergestellt werden.

- Production-Inventar und dieselbe Rollenlogik mit getrennten Variablen,
  Konten, Stores, Netzen und Units einführen;
- exklusiven Environment-Lock, Stop-vor-Start, Timeout und hostseitigen
  Rückfall auf den letzten Production-Stand implementieren;
- Backupumfang, Ziel, Aufbewahrung und Restore-SOP festlegen;
- Konfiguration und mindestens einen zustandsbehafteten Testbestand sichern
  und praktisch wiederherstellen;
- Hostreboot, fehlgeschlagenen Testing-Start, Rollback und Idempotenz testen;
- minimales Health-/Ressourcenmonitoring mit klarer Alarmgrenze einführen.

**Fertig, wenn:** Ein abgebrochener Testlauf Production ohne Zugriff auf
Production-Secrets wiederherstellen kann und Backup/Restore praktisch belegt
sind.

### Meilenstein 5 – Delivery-Kette absichern

**Ergebnis:** Änderungen werden reproduzierbar geprüft und bewusst
freigegeben, ohne PR-Code root-äquivalente Secrets zu geben.

- Gitea-Version, Actions, Branch-/Tag-Schutz und Runner-Semantik live erfassen;
- zunächst repository-spezifische statische CI ohne Serverzugang einführen;
- Werkzeug- und Collection-Versionen pinnen;
- Secret-Store, Schlüsselrotation und getrennte Testing-/Production-Rechte
  festlegen;
- privilegierten Deploymentpfad erst mit unveränderlichem, geprüftem Commit,
  Parallelität eins und bewusstem Freigabeschritt abnehmen;
- keinen Production-Schlüssel in Pull-Request-Workflows bereitstellen;
- Deploymentnachweis mit Commit, Artefaktdigests und Prüfergebnis erzeugen.

**Fertig, wenn:** Ein ungefährliches Testdeployment und anschließend ein
freigegebenes Production-Deployment einschließlich fehlgeschlagenem Lauf und
Recovery reproduzierbar nachgewiesen sind.

### Meilenstein 6 – Ersten Nutzerpfad veröffentlichen

**Ergebnis:** Genau ein klar definierter, authentifizierter Nutzerpfad ist
öffentlich nutzbar; Backend- und Managementports bleiben intern.

- anhand der Produktentscheidung LiteLLM einführen oder den alternativen
  API-Gateway-Pfad ausdrücklich spezifizieren;
- individuelle Credentials, Widerruf, Quoten/Rate Limits, Logging und
  Missbrauchsgrenzen umsetzen;
- NPM-Route, TLS und Health getrennt vom Backend abnehmen;
- bei Weboberfläche OIDC-Endpunkte und Rollen minimal freigeben;
- externe Positiv- und Negativtests für API, Adminpfade, Backendports sowie
  IPv4/IPv6 durchführen;
- Betriebs-, Schlüsselwiderrufs- und Störungs-SOP fertigstellen.

**Fertig, wenn:** Der Nutzerpfad funktioniert, direkte `llama.cpp`- und
Managementzugriffe extern scheitern und Widerruf sowie Rate Limit getestet
sind.

### Meilenstein 7 – Nachgelagerte Workloads

**Ergebnis:** Zusätzliche Anwendungen beeinträchtigen den freigegebenen
LLM-Betrieb nicht.

- OpenWebUI, GPT Researcher oder weitere Anwendungen einzeln nach Nutzen,
  Datenhaltung und Vertrauensgrenze priorisieren;
- Encoding-Produktanforderungen festlegen, CPU-/RAM-/I/O-Limits implementieren
  und unter gleichzeitiger Inferenzlast testen;
- erst danach Zeitplan, Queue, Benachrichtigung und Nutzer-SOP freigeben.

## 4. Bewusst nicht Teil der nächsten Ausbaustufe

- dynamischer `llama.cpp`-Router;
- gleichzeitiger GPU-Betrieb von Production und Testing;
- Vision und MTP vor stabiler Text-/Tool-Baseline;
- automatische Production-Updates über bewegliche Tags;
- Hochverfügbarkeitsversprechen auf dem einzelnen Host;
- neue VLAN-/Netzarchitektur ohne eigenen Netzwerk-Sprint;
- umfassende Anwendungssuite vor dem ersten abgenommenen Nutzerpfad.

## 5. Pflege und Steuerung

Der jeweils aktive Meilenstein erhält ein kleines umsetzbares Arbeitspaket mit
Owner, Risiken und Abnahmeevidenz. Neue Detaildokumente werden nur erstellt,
wenn Zielgruppe oder Betriebsverfahren wirklich eigenständig sind; ansonsten
wird das zuständige Rollen-README oder die bestehende SOP erweitert.

Eine Phase gilt nicht wegen implementierter Tasks als abgeschlossen, sondern
erst nach ihren Abnahmekriterien. Abweichungen ändern zuerst das zuständige
Fachdokument und anschließend nur bei bereichsübergreifender Wirkung diese
Roadmap und den zentralen Index.