Installation Guide

1 Prerequisites

Hardware Requirements

Production Sizing Guide

LLM inference is the primary bottleneck. A single request takes ~20 seconds (4 agent steps, 1 tool call). Ollama serializes GPU requests, so concurrent users experience linear latency increase.

To enable vLLM, set these environment variables:

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

The Ollama router model (llama3.2:3b) must remain on a separate Ollama instance to avoid GPU contention. See src/reva/vllm_client.py for details.

Recommended Models

Reva requires models with strong tool-calling (function calling) capabilities and multilingual support. Not all models perform equally well — the following recommendations are based on extensive testing with Reva's agent loop:

The router model (llama3.2:3b) classifies incoming messages and does not require tool-calling capabilities. It runs on Ollama regardless of the agent model backend.

Software Requirements

Network Requirements

• HTTPS endpoint publicly reachable from Azure Bot Framework (e.g. via reverse proxy with TLS termination)
• Outbound access to login.microsoftonline.com and smba.trafficmanager.net (Teams)
• Access to your Digital.ai Release instance (HTTP/HTTPS)
• Access to Jira Cloud (HTTPS) — if using Jira integration

2 Azure Bot Registration

Reva communicates with Microsoft Teams through the Azure Bot Framework. You need to register a bot in your Azure tenant.

2.1 Create an App Registration

1. Go to Azure Portal → Microsoft Entra ID → App registrations → New registration
2. Name: Reva
3. Supported account types: Accounts in this organizational directory only (Single Tenant)
4. Click Register
5. Go to Certificates & secrets → New client secret
6. Copy the secret value immediately — it is shown only once

2.2 Create an Azure Bot Resource

1. In Azure Portal, search for Azure Bot → Create
2. Bot handle: Reva
3. Pricing tier: F0 (free — sufficient for Teams)
4. App type: Single Tenant
5. Use existing app registration → enter the App ID from step 2.1
6. Data residency: Local (EU: westeurope recommended)

2.3 Configure Messaging Endpoint

In the Azure Bot resource, go to Configuration and set the messaging endpoint:

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

2.4 Enable Teams Channel

1. In the Azure Bot resource, go to Channels
2. Click Microsoft Teams (Commercial) → Apply

3 Download & Authenticate

3.1 Extract the Deployment Package

Download the deployment package provided by X-idra and extract it:

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

3.2 Authenticate with the Container Registry

Log in to the GitHub Container Registry using the credentials provided by X-idra:

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

3.3 Pull the Reva Image

docker compose pull

4 Generate Secrets

All sensitive credentials are stored as files in secrets/ (gitignored). Both Docker Compose and Kubernetes deployments use these same files.

./bin/generate-secrets.sh

The script auto-generates a PostgreSQL admin password, SSL certificates (self-signed CA + server cert), a database URL secret file, and a webhook secret, then prompts for:

5 Configure Environment

cp .env.example .env

Required Settings

LLM Model Setup

Reva uses two models: a small router model for message classification and a larger agent model for tool-calling:

ollama pull llama3.2:3b     # Router (fast, small)
ollama pull qwen3:14b       # Agent (tool-calling, multilingual)
ollama pull nomic-embed-text  # Embeddings (for cross-session memory)

Cloud LLM Providers (Alternative)

Instead of Ollama, you can use a cloud LLM provider:

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

6 Deploy

Choose your deployment target:

docker compose up -d

docker compose ps

NAME            STATUS              PORTS
reva            Up (healthy)        0.0.0.0:3978→8000/tcp
reva-postgres   Up (healthy)        5432/tcp
reva-redis      Up (healthy)        6379/tcp

backend reva
    server reva 127.0.0.1:3978 check

# Manual backup
./bin/backup-db.sh

# Automated (add to crontab)
0 2 * * * /path/to/reva/bin/backup-db.sh

# Install k3s (single-node, includes Traefik ingress)
curl -sfL https://get.k3s.io | sh -

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

# Verify
kubectl get nodes

# Full deploy (build image + create secrets + apply manifests)
./bin/k8s-deploy.sh

# Or step by step:
./bin/k8s-deploy.sh --build-only    # Build image and import to k3s
./bin/k8s-deploy.sh --secrets       # Create/update Kubernetes secrets
./bin/k8s-deploy.sh --apply-only    # Apply manifests only (no build)

# Check all pods are running
kubectl get pods -n reva

# Expected: 3/3 READY for reva, 1/1 for postgres and redis
NAME                     READY   STATUS    RESTARTS   AGE
reva-xxxxx-yyyyy         3/3     Running   0          2m
postgres-0               1/1     Running   0          2m
redis-xxxxx-yyyyy        1/1     Running   0          2m

# View logs
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

# Restart
kubectl rollout restart deployment/reva -n reva

# Manual database backup
kubectl create job --from=cronjob/db-backup db-backup-manual -n reva

# Rollback to previous version
kubectl rollout undo deployment/reva -n reva

# Generate self-signed TLS certificate
./bin/generate-k8s-tls.sh

# Or use cert-manager for production
# traefik.ingress.kubernetes.io/router.entrypoints: websecure
# cert-manager.io/cluster-issuer: letsencrypt-prod

kubectl apply -k k8s/
kubectl rollout restart deployment/reva -n reva

7 Teams App Sideloading

7.1 Prepare the App Package

Run the manifest configurator script. It prompts for your Azure App ID and bot endpoint domain, then creates the Teams app package:

./bin/configure-manifest.sh

You only need to provide two values:

• Azure App ID — from step 2.1 (used for both id and botId)
• Bot endpoint domain — e.g. revaapi.example.com

The developer section (company name, URLs) stays as X-idra Systems GmbH.

7.2 Enable Custom App Uploads

In the Teams Admin Center → Teams apps → Setup policies → enable Upload custom apps.

7.3 Sideload the App

1. Open Microsoft Teams → Apps → Manage your apps → Upload an app
2. Select Upload a custom app → choose reva-teams-app.zip
3. Click Add

8 Verify Installation

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())"

Expected response:

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

Functional Test

In Microsoft Teams, send these messages to Reva:

1. “Hello” — Reva should greet you
2. “List all active releases” — Reva should query Release and show results
3. “Show my dashboard” — personal release overview

9 Optional Integrations

Jira Cloud

REVA_JIRA_URL=https://yourorg.atlassian.net
REVA_JIRA_USERNAME=your-email@company.com

Ensure the reva_jira_token secret file contains a valid Atlassian API token.

LDAP Group Resolution

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

Release Webhook Notifications

Copy plugins/xlr-reva-notify-plugin-1.0.4.jar to your Digital.ai Release server's plugin directory and restart Release. Then point the webhook to:

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

Autonomous Monitoring

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

User Authorization

REVA_AUTH_ENABLED=true
REVA_AUTH_USER_MAP=TeamsName1=releaseUser1,TeamsName2=releaseUser2

Cross-Session Memory

Reva can remember user preferences and context across conversations. Memories are stored per user with semantic deduplication and automatic cleanup.

MEMORY_ENABLED=true
MEMORY_EXTRACTION_ENABLED=true

Requires the nomic-embed-text embedding model and pgvector (included in the default PostgreSQL image).

10 Troubleshooting

Cannot pull image

If docker compose pull fails with an authentication error:

• Verify you are logged in: docker login ghcr.io
• Check that your GHCR_TOKEN has not expired
• Ensure REVA_VERSION in .env matches a published version

Health check returns 503

MCP servers failed to connect. Check credentials, network access, and logs:

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 messages not arriving

• Verify the messaging endpoint in Azure Bot Configuration matches your public URL
• Check that HTTPS is correctly terminated
• Ensure REVA_MICROSOFT_APP_ID and REVA_MICROSOFT_APP_TENANT_ID are set
• Check logs for JWT validation errors

MCP containers not starting (Docker Compose)

docker ps                    # Check Docker socket access
docker pull xebialabsearlyaccess/dai-release-mcp:25.3.1-beta.212
docker pull ghcr.io/sooperset/mcp-atlassian:0.21.0

MCP sidecars not ready (Kubernetes)

# Check sidecar status
kubectl describe pod -n reva -l app=reva

# Verify ConfigMaps exist
kubectl get configmap -n reva

LLM responses are slow

• Ensure Ollama runs on a machine with a GPU
• Do not set OLLAMA_NUM_PARALLEL > 1 with less than 24 GB VRAM
• Agent model is configured in config/agent_roles.yaml, not in .env

Getting Help

Contact us at info@x-idra.de.

What’s Next

Installation complete? Here’s what to do next:

• Getting Started Guide — Your first 10 minutes with Reva: example queries, tips, and troubleshooting
• Compatibility Matrix — Supported versions of Release, Jira, Kubernetes, Docker, Ollama, and GPUs
• Monitoring Setup — Prometheus + Grafana dashboard for production observability
• Capacity Planning — GPU sizing, users per instance, and scaling guidance
• Upgrade Guide — Step-by-step version upgrades and rollback procedures
• Support & SLA — Support tiers, response times, and escalation process