mindnet/docs/admin_guide.md

# Mindnet v2.4 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.4.md`
**Stand:** 2025-12-10
**Status:** **FINAL** (Inkl. Frontend Deployment & Interview Config)
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.4.md`.

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

---

## 1. Zielgruppe & Scope

Mindnet ist als **Multi-Service-Architektur** konzipiert, die lokal oder auf einem privaten Server läuft.
Wir unterscheiden strikt zwischen:
* **Production:** Backend (8001) + Frontend (8501). Stabiler `main` Branch.
* **Development:** Backend (8002) + Frontend (8502). 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), Ollama (für LLM).
* **Hardware:**
    * CPU: 4+ Cores empfohlen (für Import & Inference).
    * RAM: Min. 8GB empfohlen (4GB System + 4GB für Phi-3/Qdrant).
    * 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
    
    # 3. Dependencies installieren (inkl. Streamlit)
    pip install -r requirements.txt
    
    # 4. 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 Ollama Setup (LLM Service)
Mindnet benötigt einen lokalen LLM-Server für den Chat.

    # 1. Installieren (Linux Script)
    curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh
    
    # 2. Modell laden (Phi-3 Mini für CPU-Performance)
    ollama pull phi3:mini
    
    # 3. Testen
    curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'

### 2.5 Konfiguration (ENV)
Erstelle eine `.env` Datei im Root-Verzeichnis. Die neuen Settings für WP-06/WP-07 (Timeout, Decision Config) sind essenziell für stabilen Betrieb auf CPUs.

    # Qdrant Verbindung
    QDRANT_URL="http://localhost:6333"
    
    # Mindnet Core Settings
    COLLECTION_PREFIX="mindnet" 
    MINDNET_TYPES_FILE="./config/types.yaml"
    
    # LLM / RAG Settings
    MINDNET_LLM_MODEL="phi3:mini"
    MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
    
    # Config & Timeouts
    MINDNET_PROMPTS_PATH="./config/prompts.yaml"
    MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
    MINDNET_LLM_TIMEOUT=300.0

### 2.6 Deployment via Systemd (Backend & Frontend)

Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit).

**Production Backend (`/etc/systemd/system/mindnet-prod.service`):**

    [Unit]
    Description=Mindnet API Prod (8001)
    After=network.target
    
    [Service]
    User=llmadmin
    Group=llmadmin
    WorkingDirectory=/home/llmadmin/mindnet
    ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
    Restart=always
    RestartSec=5
    
    [Install]
    WantedBy=multi-user.target

**Production Frontend (`/etc/systemd/system/mindnet-ui-prod.service`):**

    [Unit]
    Description=Mindnet UI Prod (8501)
    After=mindnet-prod.service
    
    [Service]
    User=llmadmin
    Group=llmadmin
    WorkingDirectory=/home/llmadmin/mindnet
    
    # Environment Variables
    Environment="MINDNET_API_URL=http://localhost:8001"
    Environment="MINDNET_API_TIMEOUT=300"
    Environment="STREAMLIT_SERVER_PORT=8501"
    Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
    Environment="STREAMLIT_SERVER_HEADLESS=true"
    
    ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
    Restart=always
    RestartSec=5
    
    [Install]
    WantedBy=multi-user.target

**Firewall (UFW):**
Öffne die Ports für den Zugriff:

    sudo ufw allow 8501/tcp  # Prod UI
    sudo ufw allow 8502/tcp  # Dev UI (falls gewünscht)

---

## 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

### 3.2 Health-Checks
Prüfe regelmäßig, ob alle Komponenten laufen.

    sudo systemctl status mindnet-prod
    sudo systemctl status mindnet-ui-prod
    sudo systemctl status ollama

### 3.3 Logs & Monitoring
* **Backend Fehler:** `journalctl -u mindnet-prod -f`
* **Frontend Fehler:** `journalctl -u mindnet-ui-prod -f`
    * Achte auf "Timeout"-Meldungen im Frontend, wenn das Backend zu langsam antwortet.
* **LLM Fehler:** `journalctl -u ollama -f`
* **Fachliche Logs:** `data/logs/search_history.jsonl`

---

## 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.  **Dienste neustarten (Zwingend!):**
    
        sudo systemctl restart mindnet-prod
        sudo systemctl restart mindnet-ui-prod

4.  **Schema-Migration (falls nötig):**
    
        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**.

### 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 Verlust des Trainingsmaterials für Self-Tuning.

### 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**.
* **Frontend:** Streamlit auf Port 8501 ist offen. Nutze Nginx Basic Auth oder VPN.
* **API:** Sollte nicht direkt im öffentlichen Netz stehen.
* **Qdrant:** Auf `127.0.0.1` beschränken.

### 6.2 Typen-Governance
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global und erfordern Tests.