# Ghostnet.AI Infrastruktur

Dokumentation für die Infrastruktur eines privaten Homelabs mit öffentlich erreichbaren Webdiensten, einem WireGuard-Zugang und einem dedizierten KI-Server. Dieses Repository hält Architekturentscheidungen, den belegten Betriebsstand und Verfahren für Einrichtung, Betrieb und Sicherheitsabnahme fest.

> **Projektstand: 14.10.2026.** Pi-hole/Split-DNS, WireGuard-Rollenpolicy und
> der per Ansible reproduzierbare Keycloak-/PostgreSQL-Stack sind produktiv
> abgenommen. Der öffentliche Keycloak-Adminpfad ist gesperrt, der interne
> HTTPS-Adminpfad funktioniert und der reale Vaultwarden-OIDC-Login wurde
> bestätigt. Dauerhaftes LLM-Serving und Encoding sind noch nicht installiert.

## Überblick

```mermaid
flowchart LR
    Internet --> Router[Fritzbox]
    Router -->|HTTP/HTTPS| NPM[Nginx Proxy Manager]
    Router -->|WireGuard| VPN[wg-easy]
    NPM --> Apps[Webdienste in eigenen LXCs]
    VPN --> LAN[Heimnetz]
    LAN --> PVE[Proxmox und Service-LXCs]
    LAN --> AI[KI-Server]
    NPM -.-> AI
```

Der Reverse Proxy und das VPN-Gateway laufen in getrennten Proxmox-LXCs. Weitere Webdienste befinden sich in eigenen LXCs. Der physische KI-Server ist für lokale Inferenz und darauf aufbauende Anwendungen vorgesehen. Die gestrichelte Verbindung zum KI-Server beschreibt einen **geplanten** Veröffentlichungsweg für LLM-Anwendungen; die Dienste sind dort noch nicht installiert.

Die drei vorgesehenen VPN-Netzwerkrollen sind **Familie** (gesamtes Heimnetz), **Server Admin** (bestätigte Server und Service-LXCs) und **LLM Admin** (nur KI-Server). Der derzeit einzige Peer `ghost-laptop` ist als Server Admin durch native nftables-Regeln abgenommen. Anwendungsanmeldung, SSH-Schlüssel und API-Schlüssel bleiben zusätzliche, eigenständige Zugangskontrollen.

## Aktueller Stand

| Bereich | Belegter Stand | Nächster Nachweis oder Schritt |
| --- | --- | --- |
| KI-Server | Debian-Basissystem, Deployment-Zugang, Podman 5.4.2, drei getrennte rootless Workload-Konten sowie zwei als `gfx1030` und als `llama.cpp`-ROCm-Geräte geprüfte RX 6900 XT | nach der Prioritätsentscheidung internes `llama.cpp`-Testing ohne öffentliche Route bereitstellen |
| VPN | wg-easy v15.4.0, native Rollenpolicy/NAT und externer Positiv-/Negativtest abgenommen | WAN-/IPv6-Exposure, Restore und GUI-HTTPS prüfen |
| Reverse Proxy | NPM auf CT 103 dokumentiert; Fail2Ban laut Betreiber fest gepinnt und wieder in Betrieb | Effektive Jails, Sperren und Wiederanlauf prüfen |
| Identität | CT 102 per Ansible mit Podman/PostgreSQL reproduziert; interner Adminpfad, öffentliche Sperre, Reboot und realer Vaultwarden-OIDC-Login abgenommen | Stabilisierungsphase und praktischen CT-104-Rückfalltest abschließen |

Der [Dokumentationsindex](docs/GNAI-000-DOC_Index.md) enthält die datierten Quellen, offenen Angaben und Abnahmegrenzen. Er ist die maßgebliche Übersicht für den aktuellen Projektstand. Eine Zielbeschreibung in diesem README oder den Architekturdokumenten ist kein Nachweis für eine bereits wirksame Konfiguration.

## Dokumentation lesen

| Einstieg | Inhalt |
| --- | --- |
| [Dokumentationsindex und Projektstand](docs/GNAI-000-DOC_Index.md) | Dokumentenübersicht, bestätigte Entscheidungen und offene Befunde |
| [High-Level-Implementierungsplan](docs/GNAI-001-PLAN_Project-Roadmap.md) | priorisierte nächste Schritte, Entscheidungstore und messbare Abschlusskriterien |
| [Plattform-Dokumentation](docs/platform/README.md) | Hostbasis, Zugriffsmodell, Reverse Proxy und VPN |
| [KI-Dokumentation](docs/platform/llm-server/ai/README.md) | KI-Zielarchitektur, Ansible-Planung, Modellbewertung und technische `llama.cpp`-Sollkonfiguration |
| [Video-Encoding](docs/platform/llm-server/encoding/GNENC-000-DOC_Index.md) | getrennter Planungs- und späterer SOP-Bereich für den CPU-Encoding-Workload |
| [LLM-Server-Automation](llm-server/ansible/README.md) | Host-Baseline, Podman, Workload-Konten, AMD-GPU-Zugriff und rootless ROCm-Probe |
| [Keycloak-CT-102-Automation](proxmox/lxc/ct-102-keycloak/ansible/README.md) | Inventare, Rollen, Restore- und Produktionsverifikation für CT 102 |

## Arbeiten mit dem Repository

Dieses Repository enthält Dokumentation und hostbezogene Ansible-Projekte.
Der physische KI-Server liegt unter `llm-server/`, Proxmox-Gäste unter
`proxmox/lxc/<ct-id>-<dienst>/`; nur tatsächlich wiederverwendbare Rollen und
Control-Node-Pins liegen unter `shared/ansible/`. Vor einer
Infrastrukturänderung den Ist-Stand am betroffenen Host prüfen, die passende
Fachanleitung lesen und die dort genannten Abnahmeschritte dokumentieren.

WireGuard-Profile enthalten private Schlüssel. Sie gehören nicht in Git,
Ausgaben oder freigegebene Dokumente. Die geschützte lokale Ablage liegt
außerhalb des Repositorys; eine Ignore-Regel ist kein Ersatz für sichere
Aufbewahrung.

Änderungen am Projektstand sollten zuerst im zuständigen Fachdokument mit Datum und Beleg erfasst werden. Anschließend den [Index](docs/GNAI-000-DOC_Index.md) und diese README aktualisieren, wenn sich eine übergreifende Aussage geändert hat.