mindnet/docs/admin_guide.md

# Mindnet v2.2 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
**Stand:** 2025-12-08
**Status:** **FINAL** (Konsolidiert WP02–WP04c)
**Quellen:** `Handbuch.md`, `mindnet_v2_implementation_playbook.md`, `mindnet_technical_architecture.md`, `Programmplan_V2.2.md`.

> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz.

---

## 1. Zielgruppe & Scope

Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
Wir unterscheiden strikt zwischen:
* **Production (Port 8001):** Stabiler `main` Branch.
* **Development (Port 8002):** Experimentelle Feature-Branches.

---

## 2. Initial Setup & Installation

### 2.1 Systemvoraussetzungen
* **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
* **Runtime:** Python 3.10+, Docker (für Qdrant).
* **Hardware:**
    * CPU: 2+ Cores.
    * RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index).
    * Disk: SSD empfohlen für Qdrant-Performance.

### 2.2 Installation (Code)
    # 1. Repository klonen
    git clone <repo-url> /home/llmadmin/mindnet
    cd /home/llmadmin/mindnet
    
    # 2. Umgebung einrichten
    python3 -m venv .venv
    source .venv/bin/activate
    pip install -r requirements.txt
    
    # 3. Verzeichnisse anlegen
    mkdir -p logs qdrant_storage data/logs

### 2.3 Qdrant Setup (Docker)
Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
    docker run -d \
      --name mindnet_qdrant \
      --restart always \
      -p 6333:6333 \
      -v $(pwd)/qdrant_storage:/qdrant/storage \
      qdrant/qdrant

### 2.4 Konfiguration (ENV)
Erstelle eine `.env` Datei im Root-Verzeichnis. Diese Variablen steuern das Verhalten der Skripte und der API.

    # Qdrant Verbindung
    QDRANT_URL="http://localhost:6333"
    QDRANT_API_KEY=""  # Leer lassen für lokale Instanzen ohne Auth
    
    # Mindnet Core Settings
    COLLECTION_PREFIX="mindnet" # "mindnet_dev" für Dev-Umgebung
    MINDNET_TYPES_FILE="./config/types.yaml"
    MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
    
    # Embedding Settings (Default: all-MiniLM-L6-v2)
    VECTOR_DIM=384
    
    # Import-Strategie
    MINDNET_HASH_COMPARE="Body" 
    MINDNET_HASH_SOURCE="parsed"

### 2.5 Deployment via Systemd (Standard ab v2.2.1)
Mindnet wird nicht mehr manuell gestartet, sondern als Systemdienst.

**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
* Läuft auf Port 8001.
* Autostart (`enabled`).
* Restart Policy: `always` (heilt Abstürze automatisch).

**Development Service (`/etc/systemd/system/mindnet-dev.service`):**
* Läuft auf Port 8002.
* Getrennter Ordner (`~/mindnet_dev`).

---

## 3. Betrieb im Alltag

### 3.1 Regelmäßige Importe
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden.

**Cronjob-Beispiel (stündlich):**
    0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1

* `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen.
* `--sync-deletes`: Entfernt Notizen aus dem Index, die im Vault gelöscht wurden.

### 3.2 Health-Checks
Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten.

**System Status:**
    sudo systemctl status mindnet-prod

**Logischer Smoke-Test:**
    python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query

### 3.3 Logs & Monitoring
Seit v2.2.1 werden technische Logs im Systemd Journal und fachliche Logs in JSONL-Dateien gespeichert.

* **Technische Fehler (Live):**
    `journalctl -u mindnet-prod -f`
* **Fachliche Logs (Data Flywheel):**
    `/home/llmadmin/mindnet/data/logs/search_history.jsonl`
    `/home/llmadmin/mindnet/data/logs/feedback.jsonl`

> **Hinweis:** Die JSONL-Logs wachsen endlos ("Append Only"). Richte bei Bedarf `logrotate` ein oder archiviere alte Logs. Lösche sie nicht, da sie die Basis für WP08 (Self-Tuning) sind.

---

## 4. Update-Prozess

Wenn neue Versionen ausgerollt werden (Deployment):

1.  **Code aktualisieren:**
        cd /home/llmadmin/mindnet
        git pull origin main
2.  **Dependencies prüfen:**
        source .venv/bin/activate
        pip install -r requirements.txt
3.  **Dienst neustarten (Zwingend!):**
        sudo systemctl restart mindnet-prod
4.  **Schema-Migration (falls nötig):**
    Bei Änderungen an `types.yaml` oder Index-Strukturen:
        python3 -m scripts.import_markdown ... --apply

---

## 5. Backup & Restore

Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).

### 5.1 Vault-Backup (Priorität 1)
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).

### 5.2 Qdrant-Snapshots (Priorität 2)
Für schnelle Wiederherstellung des Suchindex.
    docker stop mindnet_qdrant
    tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
    docker start mindnet_qdrant

### 5.3 Log-Daten (Priorität 3)
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.

### 5.4 Notfall-Wiederherstellung (Rebuild)
Wenn die Datenbank korrupt ist:
    # 1. DB komplett leeren (Wipe)
    python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
    # 2. Alles neu importieren
    python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply

---

## 6. Governance & Sicherheit

### 6.1 Zugriffsschutz
Mindnet hat aktuell **keine integrierte Authentifizierung**.
* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird.
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.

### 6.2 Typen-Governance
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global.
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.