mindnet/docs/04_Operations/04_deployment_guide.md

doc_type	audience	scope	status	version	context
operations_manual	devops, deployment_engineer	deployment, ci_cd, rollout, versioning	active	2.9.1	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:

# 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

[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

[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:

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

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:

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

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

cd ~/mindnet
git log --oneline -10  # Finde letzten guten Commit
git checkout <commit-hash>
sudo systemctl restart mindnet-prod

Methode 2: Git Reset (Vorsicht!)

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)
• 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

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

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

8.2 Funktionalität

# 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

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

curl http://localhost:8001/healthz

Response:

{
  "status": "ok",
  "qdrant": "http://localhost:6333",
  "prefix": "mindnet"
}

Monitoring-Script:

python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict

10.2 Log-Monitoring

Systemd Journal:

# 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 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
• Server Operations: Siehe Server Operations Manual
• Troubleshooting: Siehe Admin Operations - Troubleshooting

---

Letzte Aktualisierung: 2025-01-XX
Version: 2.9.1