Installationsanleitung

1 Voraussetzungen

Hardware-Anforderungen

Produktions-Skalierung

LLM-Inferenz ist der primäre Engpass. Eine einzelne Anfrage dauert ~20 Sekunden (4 Agent-Schritte, 1 Tool-Aufruf). Ollama serialisiert GPU-Anfragen — bei gleichzeitigen Nutzern steigt die Latenz linear.

Um vLLM zu aktivieren, setzen Sie diese Umgebungsvariablen:

REVA_VLLM_URL=http://gpu-server:8100/v1
REVA_VLLM_API_KEY=beliebiger-string

Das Ollama-Router-Modell (llama3.2:3b) muss auf einer separaten Ollama-Instanz verbleiben, um GPU-Konflikte zu vermeiden. Details siehe src/reva/vllm_client.py.

Empfohlene Modelle

Reva benötigt Modelle mit starken Tool-Calling-Fähigkeiten (Function Calling) und Mehrsprachigkeit. Nicht alle Modelle liefern gleich gute Ergebnisse — folgende Empfehlungen basieren auf umfangreichen Tests mit Revas Agent-Loop:

Das Router-Modell (llama3.2:3b) klassifiziert eingehende Nachrichten und benötigt keine Tool-Calling-Fähigkeiten. Es läuft auf Ollama, unabhängig vom Agent-Modell-Backend.

Software-Anforderungen

Netzwerk-Anforderungen

• HTTPS-Endpunkt, öffentlich erreichbar vom Azure Bot Framework
• Ausgehender Zugriff auf login.microsoftonline.com und smba.trafficmanager.net
• Zugriff auf Ihre Digital.ai Release-Instanz
• Zugriff auf Jira Cloud — falls gewünscht

2 Azure-Bot-Registrierung

Reva kommuniziert mit Microsoft Teams über das Azure Bot Framework.

2.1 App-Registrierung erstellen

1. Azure Portal → Microsoft Entra ID → App-Registrierungen → Neue Registrierung
2. Name: Reva, Kontotyp: Einzelmandant
3. Zertifikate & Geheimnisse → Neuer geheimer Clientschlüssel
4. Geheimniswert sofort kopieren — er wird nur einmal angezeigt

2.2 Azure-Bot-Ressource erstellen

1. Azure Bot → Erstellen, Tarif: F0, App-Typ: Einzelmandant
2. Vorhandene App-Registrierung verwenden → App-ID eingeben
3. Datenresidenz: Lokal (westeurope)

2.3 Messaging-Endpunkt

https://ihre-domain.example.com/api/messages

2.4 Teams-Kanal aktivieren

Kanäle → Microsoft Teams (Commercial) → Übernehmen

3 Download & Authentifizierung

3.1 Deployment-Paket entpacken

Laden Sie das von X-idra bereitgestellte Deployment-Paket herunter und entpacken Sie es:

tar xzf reva-1.0.4.tar.gz
cd reva-1.0.4

3.2 Container-Registry authentifizieren

Melden Sie sich mit den von X-idra bereitgestellten Zugangsdaten an der GitHub Container Registry an:

echo "$GHCR_TOKEN" | docker login ghcr.io -u "$GHCR_USER" --password-stdin

3.3 Reva-Image herunterladen

docker compose pull

4 Secrets generieren

Alle sensiblen Zugangsdaten werden als Dateien in secrets/ gespeichert. Sowohl Docker Compose als auch Kubernetes verwenden dieselben Dateien.

./bin/generate-secrets.sh

Das Skript generiert automatisch ein PostgreSQL-Passwort, ein Admin-Passwort, SSL-Zertifikate (selbstsignierte CA + Server-Zertifikat), einen Webhook-Secret und eine Datenbank-URL. Anschließend werden interaktive Eingaben für externe Zugangsdaten abgefragt:

5 Umgebung konfigurieren

cp .env.example .env

Erforderliche Einstellungen

LLM-Modell-Setup

ollama pull llama3.2:3b     # Router (schnell, klein)
ollama pull qwen3:14b       # Agent (Tool-Calling, mehrsprachig)
ollama pull nomic-embed-text  # Embeddings (für sitzungsübergreifendes Gedächtnis)

Cloud-LLM-Anbieter (Alternative)

REVA_OPENAI_API_KEY=sk-...          # OpenAI
REVA_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic Claude

6 Bereitstellung

Wählen Sie Ihre Zielumgebung:

docker compose up -d

docker compose ps    # Alle Services sollten "Up (healthy)" zeigen

backend reva
    server reva 127.0.0.1:3978 check

./bin/backup-db.sh                                    # Manuell
0 2 * * * /pfad/zu/reva/bin/backup-db.sh              # Crontab

# k3s installieren (Single-Node, inkl. Traefik Ingress)
curl -sfL https://get.k3s.io | sh -

# Kubeconfig einrichten
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

kubectl get nodes

# Vollständiges Deployment
./bin/k8s-deploy.sh

# Oder schrittweise:
./bin/k8s-deploy.sh --build-only    # Image bauen und importieren
./bin/k8s-deploy.sh --secrets       # Kubernetes-Secrets erstellen
./bin/k8s-deploy.sh --apply-only    # Nur Manifeste anwenden

kubectl get pods -n reva

# Erwartet: 3/3 READY für reva, 1/1 für postgres und redis

# Logs anzeigen
kubectl logs -n reva -l app=reva -c reva -f           # App
kubectl logs -n reva -l app=reva -c release-mcp -f    # Release MCP
kubectl logs -n reva -l app=reva -c jira-mcp -f       # Jira MCP

# Neustart
kubectl rollout restart deployment/reva -n reva

# Manuelles Datenbank-Backup
kubectl create job --from=cronjob/db-backup db-backup-manual -n reva

# Rollback auf vorherige Version
kubectl rollout undo deployment/reva -n reva

# Selbstsigniertes TLS-Zertifikat generieren
./bin/generate-k8s-tls.sh

# Oder cert-manager für Produktion
# cert-manager.io/cluster-issuer: letsencrypt-prod

7 Teams-App Sideloading

7.1 App-Paket vorbereiten

Führen Sie das Manifest-Konfigurationsskript aus. Es fragt nach Ihrer Azure App ID und Bot-Endpunkt-Domain und erstellt das Teams-App-Paket:

./bin/configure-manifest.sh

Sie müssen nur zwei Werte angeben:

• Azure App ID — aus Schritt 2.1 (wird für id und botId verwendet)
• Bot-Endpunkt-Domain — z. B. revaapi.example.com

Der Entwickler-Abschnitt (Firmenname, URLs) bleibt X-idra Systems GmbH.

7.2 Benutzerdefinierte Apps aktivieren

Teams Admin Center → Einrichtungsrichtlinien → Benutzerdefinierte Apps hochladen aktivieren.

7.3 App sideloaden

1. Teams → Apps → Apps verwalten → App hochladen
2. Benutzerdefinierte App hochladen → reva-teams-app.zip
3. Hinzufügen

8 Installation prüfen

Health Check

curl http://localhost:3978/api/health

kubectl exec -n reva deploy/reva -c reva -- \
  python -c "import urllib.request; print(urllib.request.urlopen('http://localhost:8000/api/health').read().decode())"

Erwartete Antwort:

{
  "status": "ok",
  "adapter_initialized": true,
  "db": true,
  "mcp": {
    "release": { "connected": true, "tools": 38 },
    "jira": { "connected": true, "tools": 29 }
  }
}

Funktionstest

1. „Hallo“ — Reva sollte Sie begrüßen
2. „Zeige alle aktiven Releases“ — Ergebnisse aus Release
3. „Mein Dashboard“ — persönliche Release-Übersicht

9 Optionale Integrationen

Jira Cloud

REVA_JIRA_URL=https://ihrorg.atlassian.net
REVA_JIRA_USERNAME=ihre-email@firma.com

LDAP-Gruppenauflösung

REVA_LDAP_URL=ldap://ldap.firma.de:389
REVA_LDAP_BIND_DN=cn=reva,ou=services,dc=firma,dc=de
REVA_LDAP_GROUP_BASE=ou=groups,dc=firma,dc=de

Release-Webhook-Benachrichtigungen

Kopieren Sie plugins/xlr-reva-notify-plugin-1.0.4.jar in das Plugin-Verzeichnis Ihres Digital.ai Release Servers und starten Sie Release neu. Webhook-Ziel konfigurieren:

https://ihre-domain.example.com/api/notify

Autonome Überwachung

REVA_MONITOR_ENABLED=true
REVA_MONITOR_INTERVAL=300
REVA_MONITOR_OVERDUE_THRESHOLD_HOURS=24
REVA_MONITOR_STALE_APPROVAL_HOURS=48

Benutzer-Autorisierung

REVA_AUTH_ENABLED=true
REVA_AUTH_USER_MAP=Name1=releaseUser1,Name2=releaseUser2

Sitzungsübergreifendes Gedächtnis

Reva kann Benutzerpräferenzen und Kontext über Gespräche hinweg speichern. Erinnerungen werden pro Benutzer mit semantischer Deduplizierung und automatischer Bereinigung gespeichert.

MEMORY_ENABLED=true
MEMORY_EXTRACTION_ENABLED=true

Benötigt das Embedding-Modell nomic-embed-text und pgvector (im Standard-PostgreSQL-Image enthalten).

10 Fehlerbehebung

Image kann nicht geladen werden

Falls docker compose pull mit einem Authentifizierungsfehler fehlschlägt:

• Anmeldung prüfen: docker login ghcr.io
• Sicherstellen, dass Ihr GHCR_TOKEN nicht abgelaufen ist
• REVA_VERSION in .env auf eine veröffentlichte Version prüfen

Health Check gibt 503 zurück

docker compose logs reva | grep -i "mcp\|error"

kubectl logs -n reva -l app=reva -c reva | grep -i "mcp\|error"
kubectl logs -n reva -l app=reva -c release-mcp
kubectl logs -n reva -l app=reva -c jira-mcp

Teams-Nachrichten kommen nicht an

• Messaging-Endpunkt in Azure prüfen
• HTTPS-Terminierung und Weiterleitung prüfen
• REVA_MICROSOFT_APP_ID und REVA_MICROSOFT_APP_TENANT_ID gesetzt?
• Logs auf JWT-Validierungsfehler prüfen

MCP-Container starten nicht (Docker Compose)

docker ps
docker pull xebialabsearlyaccess/dai-release-mcp:25.3.1-beta.212
docker pull ghcr.io/sooperset/mcp-atlassian:0.21.0

MCP-Sidecars nicht bereit (Kubernetes)

kubectl describe pod -n reva -l app=reva
kubectl get configmap -n reva

LLM-Antworten sind langsam

• Ollama auf GPU-Maschine?
• OLLAMA_NUM_PARALLEL nicht > 1 bei < 24 GB VRAM
• Agent-Modell in config/agent_roles.yaml, nicht in .env

Hilfe

info@x-idra.de

Nächste Schritte

Installation abgeschlossen? So geht es weiter:

• Erste Schritte — Die ersten 10 Minuten mit Reva: Beispielabfragen, Tipps und Fehlerbehebung
• Kompatibilitätsmatrix — Unterstützte Versionen von Release, Jira, Kubernetes, Docker, Ollama und GPUs
• Monitoring einrichten — Prometheus + Grafana-Dashboard für Produktionsüberwachung
• Kapazitätsplanung — GPU-Dimensionierung, Benutzer pro Instanz und Skalierungsempfehlungen
• Upgrade-Anleitung — Schritt-für-Schritt-Upgrades und Rollback-Verfahren
• Support & SLA — Support-Stufen, Reaktionszeiten und Eskalationsprozess