mindnet/docs/admin_guide.md

Mindnet v2.2 – Admin Guide

Datei: docs/mindnet_admin_guide_v2.2.md Stand: 2025-12-08 Status: FINAL (Inkl. RAG & LLM Ops) Quellen: Handbuch.md, mindnet_developer_guide_v2.2.md.

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

---

📖 Inhaltsverzeichnis (Klicken zum Öffnen)

• Mindnet v2.2 – Admin Guide
  • 1. Zielgruppe & Scope
  • 2. Initial Setup & Installation
    • 2.1 Systemvoraussetzungen
    • 2.2 Installation (Code)
    • 2.3 Qdrant Setup (Docker)
    • 2.4 Ollama Setup (LLM Service)
    • 2.5 Konfiguration (ENV)
    • 2.6 Deployment via Systemd
  • 3. Betrieb im Alltag
    • 3.1 Regelmäßige Importe
    • 3.2 Health-Checks
    • 3.3 Logs & Monitoring
  • 4. Update-Prozess
  • 5. Backup & Restore
    • 5.1 Vault-Backup (Priorität 1)
    • 5.2 Qdrant-Snapshots (Priorität 2)
    • 5.3 Log-Daten (Priorität 3)
    • 5.4 Notfall-Wiederherstellung (Rebuild)
  • 6. Governance & Sicherheit
    • 6.1 Zugriffsschutz
    • 6.2 Typen-Governance

---

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), 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
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 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 | 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.

# Qdrant Verbindung
QDRANT_URL="http://localhost:6333"

# Mindnet Core Settings
COLLECTION_PREFIX="mindnet" 
MINDNET_TYPES_FILE="./config/types.yaml"
MINDNET_PROMPTS_PATH="./config/prompts.yaml"

# LLM Settings
MINDNET_LLM_MODEL="phi3:mini"
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"

2.6 Deployment via Systemd

Mindnet wird als Systemdienst gestartet. Ollama läuft meist als eigener Dienst (ollama.service).

Production Service (/etc/systemd/system/mindnet-prod.service):

• Läuft auf Port 8001.
• Autostart (enabled).
• Restart Policy: always.
• Abhängigkeit: Sollte nach docker und ollama starten.

---

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 drei Komponenten (API, DB, LLM) laufen.

Status prüfen: sudo systemctl status mindnet-prod sudo systemctl status ollama

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

3.3 Logs & Monitoring

• Technische Fehler (API): journalctl -u mindnet-prod -f
• LLM Fehler (Ollama): journalctl -u ollama -f
• Fachliche Logs: data/logs/search_history.jsonl

Troubleshooting Chat:

• Wenn /chat in den Timeout läuft (>300s): Prüfe, ob phi3:mini geladen ist und ob der Server überlastet ist.
• Wenn /chat halluziniert: Prüfe config/prompts.yaml und ob der Import aktuell ist.

---

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): 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) mit Basic Auth laufen.
• Qdrant: Sollte via Firewall (ufw) auf 127.0.0.1 beschränkt sein.
• Ollama: Standardmäßig hört Ollama nur auf localhost. Das ist sicher.

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.