mindnet/docs/04_Operations/04_deployment_guide.md

---
doc_type: operations_manual
audience: devops, deployment_engineer
scope: deployment, ci_cd, rollout, versioning
status: active
version: 2.9.1
context: "Vollständiger Deployment-Guide für Mindnet: CI/CD, Rollout-Strategien, Versionierung und Rollback."
---

# Deployment Guide

Dieses Dokument beschreibt die Deployment-Prozesse, CI/CD-Pipelines und Rollout-Strategien für Mindnet.

## 1. Deployment-Architektur

Mindnet läuft in einer **Multi-Environment-Architektur**:

| Environment | Ports | Zweck | User |
| :--- | :--- | :--- | :--- |
| **Production** | 8001 (API), 8501 (UI) | Live-System | `llmadmin` |
| **Development** | 8002 (API), 8502 (UI) | Test & Entwicklung | `llmadmin` |

**Wichtig:** Beide Environments teilen sich die gleiche Qdrant-Instanz, nutzen aber unterschiedliche Collection-Prefixes.

---

## 2. Deployment-Methoden

### 2.1 Automatisches Deployment (CI/CD)

**Tool:** Gitea Actions (`.gitea/workflows/deploy.yml`)

**Trigger:** Push auf `main` Branch

**Prozess:**
1. **Checkout:** Code wird ausgecheckt
2. **Stop API:** Graceful Stop des API-Services
3. **Deploy:** Rsync der whitelisted Verzeichnisse
4. **Dependencies:** Python venv & requirements aktualisieren
5. **Restart:** API-Service neu starten

**Deployierte Verzeichnisse:**
- `app/` - Backend-Code
- `scripts/` - Admin-Tools
- `config/` - Konfigurationsdateien
- `tests/` - Test-Suite
- `requirements.txt` - Dependencies

**Ausgeschlossen:**
- `.env*` - Umgebungsvariablen (bleiben auf Server)
- `.venv` - Virtuelle Umgebung (wird neu erstellt)
- `vault/` - Content (bleibt auf Server)

### 2.2 Manuelles Deployment

**Für:** Hotfixes, manuelle Rollouts, Debugging

**Prozess:**
```bash
# 1. Auf Server einloggen
ssh llmadmin@llm-node

# 2. In Produktions-Verzeichnis wechseln
cd ~/mindnet

# 3. Code aktualisieren
git fetch origin
git checkout main
git pull origin main

# 4. Dependencies aktualisieren
source .venv/bin/activate
pip install -r requirements.txt

# 5. Services neu starten
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod

# 6. Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod
```

---

## 3. Systemd Services

### 3.1 Backend Service (API)

**Datei:** `/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
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
Restart=always
RestartSec=5
Environment="MINDNET_VOCAB_PATH=/home/llmadmin/mindnet/vault/_system/dictionary/edge_vocabulary.md"

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

**Wichtig:** 
- `--env-file .env` lädt Umgebungsvariablen
- `MINDNET_VOCAB_PATH` muss absolut sein (für Edge Registry)

### 3.2 Frontend Service (UI)

**Datei:** `/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="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
```

### 3.3 Service-Management

**Befehle:**
```bash
# Status prüfen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod

# Starten
sudo systemctl start mindnet-prod
sudo systemctl start mindnet-ui-prod

# Stoppen
sudo systemctl stop mindnet-prod
sudo systemctl stop mindnet-ui-prod

# Neustart
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod

# Logs anzeigen
sudo journalctl -u mindnet-prod -f
sudo journalctl -u mindnet-ui-prod -f
```

---

## 4. Rollout-Strategien

### 4.1 Blue-Green Deployment (Empfohlen)

**Konzept:** Zwei identische Environments, Switch zwischen ihnen.

**Aktuell:** Prod/Dev als Blue-Green Setup

**Vorgehen:**
1. Deploy auf Dev (Port 8002/8502)
2. Tests auf Dev durchführen
3. Wenn erfolgreich: Deploy auf Prod (Port 8001/8501)
4. Switch erfolgt durch Service-Restart

**Vorteile:**
- Schneller Rollback (alte Version läuft noch)
- Keine Downtime
- Test vor Produktion

### 4.2 Canary Deployment (Zukünftig)

**Konzept:** Schrittweise Rollout an einen Teil der Nutzer.

**Umsetzung:**
- Load Balancer mit Traffic-Splitting
- Monitoring der Fehlerrate
- Automatischer Rollback bei Fehlern

**Status:** Noch nicht implementiert (Single-User-Szenario)

---

## 5. Versionierung & Releases

### 5.1 Version-Schema

**Format:** `v2.9.1`

- **Major (2):** Breaking Changes
- **Minor (9):** Neue Features, Backward Compatible
- **Patch (1):** Bugfixes, kleine Verbesserungen

### 5.2 Release-Prozess

**1. Feature-Entwicklung:**
```bash
git checkout -b feature/neue-funktion
# ... Entwicklung ...
git push origin feature/neue-funktion
```

**2. Testing:**
- Unit Tests
- Integration Tests
- Smoke Tests auf Dev

**3. Merge:**
```bash
# Pull Request in Gitea
# Review & Merge nach main
```

**4. Deployment:**
- Automatisch via CI/CD (bei Push auf main)
- Oder manuell (siehe 2.2)

**5. Tagging (Optional):**
```bash
git tag -a v2.9.2 -m "Release v2.9.2: Neue Funktion X"
git push origin v2.9.2
```

---

## 6. Rollback-Strategien

### 6.1 Code-Rollback

**Methode 1: Git Revert**
```bash
cd ~/mindnet
git log --oneline -10  # Finde letzten guten Commit
git checkout <commit-hash>
sudo systemctl restart mindnet-prod
```

**Methode 2: Git Reset (Vorsicht!)**
```bash
cd ~/mindnet
git reset --hard <commit-hash>
sudo systemctl restart mindnet-prod
```

### 6.2 Datenbank-Rollback

**Problem:** Code-Rollback hilft nicht bei Schema-Änderungen.

**Lösung:**
- **Qdrant-Snapshots:** Regelmäßige Backups (siehe [Server Operations Manual](04_server_operation_manual.md))
- **Collection-Versionierung:** Separate Collections pro Version (nicht empfohlen)

**Vorgehen bei Schema-Änderung:**
1. Snapshot vor Deployment erstellen
2. Deployment durchführen
3. Bei Problemen: Snapshot wiederherstellen

---

## 7. Pre-Deployment Checkliste

Vor jedem Deployment sollten folgende Punkte geprüft werden:

- [ ] **Code-Qualität:**
  - [ ] Unit Tests bestehen
  - [ ] Integration Tests bestehen
  - [ ] Linting bestanden

- [ ] **Dependencies:**
  - [ ] `requirements.txt` aktualisiert
  - [ ] Neue Dependencies dokumentiert
  - [ ] Breaking Changes in Dependencies geprüft

- [ ] **Konfiguration:**
  - [ ] `.env` Variablen dokumentiert (falls neu)
  - [ ] Config-Dateien (`types.yaml`, etc.) kompatibel
  - [ ] Edge Registry Pfad korrekt

- [ ] **Datenbank:**
  - [ ] Schema-Änderungen dokumentiert
  - [ ] Migration-Skripte vorhanden (falls nötig)
  - [ ] Backup erstellt

- [ ] **Dokumentation:**
  - [ ] Changelog aktualisiert
  - [ ] Dokumentation synchronisiert
  - [ ] Breaking Changes dokumentiert

---

## 8. Post-Deployment Validierung

Nach jedem Deployment sollten folgende Checks durchgeführt werden:

### 8.1 Service-Status

```bash
# Services laufen
sudo systemctl status mindnet-prod
sudo systemctl status mindnet-ui-prod

# Health Check
curl http://localhost:8001/healthz
```

### 8.2 Funktionalität

```bash
# API-Test
curl -X POST http://localhost:8001/query \
  -H "Content-Type: application/json" \
  -d '{"query": "test", "top_k": 1}'

# UI-Test (Manuell)
# Öffne http://localhost:8501 im Browser
```

### 8.3 Logs prüfen

```bash
# Fehler in Logs
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i error

# Warnings
sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i warning
```

---

## 9. CI/CD Pipeline Details

### 9.1 Gitea Actions Workflow

**Datei:** `.gitea/workflows/deploy.yml`

**Trigger:**
- Push auf `main` Branch
- Concurrency: Nur ein Deployment gleichzeitig

**Schritte:**
1. **Checkout:** Code aus Repository
2. **Stop API:** Graceful Stop (continue-on-error)
3. **Deploy:** Rsync der Verzeichnisse
4. **Python Setup:** Venv & Requirements
5. **Start API:** Service neu starten

**Wichtig:** 
- `.env` wird **nicht** deployed (bleibt auf Server)
- Vault wird **nicht** deployed (bleibt auf Server)

### 9.2 Deployment-Verzeichnisse

**Whitelist:**
```
app scripts schemas docker tests config requirements.txt README.md
```

**Excluded:**
- `.git/`
- `.env*`
- `.venv/`
- `vault/`
- `hf_cache/`

---

## 10. Monitoring & Alerting

### 10.1 Health Checks

**API Health Endpoint:**
```bash
curl http://localhost:8001/healthz
```

**Response:**
```json
{
  "status": "ok",
  "qdrant": "http://localhost:6333",
  "prefix": "mindnet"
}
```

**Monitoring-Script:**
```bash
python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict
```

### 10.2 Log-Monitoring

**Systemd Journal:**
```bash
# Live-Logs
sudo journalctl -u mindnet-prod -f

# Letzte 100 Zeilen
sudo journalctl -u mindnet-prod -n 100

# Seit gestern
sudo journalctl -u mindnet-prod --since "yesterday"
```

### 10.3 Metriken (Zukünftig)

**Geplante Metriken:**
- Request-Rate
- Response-Zeiten
- Fehler-Rate
- LLM-Call-Dauer
- Qdrant-Performance

**Tools:** Prometheus + Grafana (noch nicht implementiert)

---

## 11. Disaster Recovery

Siehe [Server Operations Manual](04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) für detaillierte Disaster-Recovery-Prozeduren.

**Kurzfassung:**
1. **Stage 1:** Basis-Image Restore (Bare Metal)
2. **Stage 2:** Daten-Update via Borgmatic
3. **Dienste:** Gitea, Qdrant, Ollama spezifisch wiederherstellen

---

## 12. Best Practices

### 12.1 Deployment-Zeiten

- **Produktion:** Während Wartungsfenstern (nachts, Wochenenden)
- **Development:** Jederzeit (ist Test-Umgebung)

### 12.2 Kommunikation

- **Breaking Changes:** Vorher ankündigen
- **Downtime:** Bei größeren Deployments kommunizieren
- **Rollback-Plan:** Immer bereit haben

### 12.3 Testing

- **Immer zuerst auf Dev testen**
- **Smoke Tests nach Deployment**
- **Monitoring für erste Stunden nach Deployment**

---

## 13. Weitere Informationen

- **Admin Operations:** Siehe [Admin Operations Guide](04_admin_operations.md)
- **Server Operations:** Siehe [Server Operations Manual](04_server_operation_manual.md)
- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](04_admin_operations.md#33-troubleshooting-guide)

---

**Letzte Aktualisierung:** 2025-01-XX  
**Version:** 2.9.1