---
doc_type: operations_manual
audience: admin, devops
scope: deployment, maintenance, backup, edge_registry
status: active
version: 2.7.0
context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v2.7."
---

# Admin Operations Guide

## 1. Installation & Setup

### 1.1 Voraussetzungen
* **OS:** Ubuntu 22.04+ (empfohlen).
* **Tools:** Python 3.10+, Docker, Ollama.
* **Hardware:** Min. 8GB RAM, 4 CPU Cores (für Async Import).

### 1.2 Qdrant (Docker)
Startet die Vektor-DB mit persistentem Storage auf Port 6333.

```bash
docker run -d \
  --name mindnet_qdrant \
  --restart always \
  -p 6333:6333 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant
```

### 1.3 Ollama (Modelle)
**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings.

```bash
# Modelle laden
ollama pull phi3:mini
ollama pull nomic-embed-text

# Testen
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
```

---

## 2. Deployment (Systemd Services)

Wir unterscheiden strikt zwischen **Prod** (Port 8001/8501) und **Dev** (Port 8002/8502).

### 2.1 Backend Service (`/etc/systemd/system/mindnet-prod.service`)

```ini
[Unit]
Description=Mindnet API Prod (8001)
After=network.target

[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet
# Startet Uvicorn (Async Server)
# Hinweis: Die .env muss MINDNET_VOCAB_PATH für die Edge Registry enthalten.
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
```

### 2.2 UI Service (`/etc/systemd/system/mindnet-ui-prod.service`)

```ini
[Unit]
Description=Mindnet UI Prod (8501)
After=mindnet-prod.service

[Service]
User=llmadmin
Group=llmadmin
WorkingDirectory=/home/llmadmin/mindnet

# Environment für Streamlit Port & API-Ziel
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"

# WICHTIG: Pfad zur neuen Router-Datei (ui.py)
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

---

## 3. Wartung & Monitoring

### 3.1 Regelmäßiger Import (Cron)
Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit.

```bash
# Crontab Eintrag (user: llmadmin)
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
```

### 3.2 Monitoring der Edge Registry (WP-22)
Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfen.
* **Pfad:** `data/logs/unknown_edges.jsonl`.
* **Aktion:** Wenn neue Typen häufig auftreten, sollten diese als Alias in die `01_edge_vocabulary.md` aufgenommen werden.

### 3.3 Troubleshooting Guide

**Fehler: "Registry Initialization Failure" (Neu in v2.7)**
* **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log.
* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen.

**Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"**
* Ursache: Alte Dependencies oder falsches Paket installiert.
* Lösung: Environment aktualisieren.
  ```bash
  source .venv/bin/activate
  pip uninstall streamlit-cytoscapejs
  pip install st-cytoscape
  ```

**Fehler: "Vector dimension error: expected 768, got 384"**
* Ursache: Alte DB (v2.2), neues Modell (v2.4).
* Lösung: **Full Reset** (siehe Kap. 4.2).

**Fehler: Import sehr langsam**
* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.

**Fehler: UI "Read timed out"**
* Ursache: Backend braucht für Smart Edges länger als 60s.
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).

---

## 4. Backup & Restore

### 4.1 Qdrant Snapshot
Sichert den Vektor-Index.

```bash
docker stop mindnet_qdrant
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
docker start mindnet_qdrant
```

### 4.2 Notfall-Rebuild (Clean Slate)
Wenn alles inkonsistent ist oder Dimensionen sich ändern:

```bash
# 1. DB löschen
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Neu importieren (Force Hash recalculation)
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
```