Operations Guide

Health Check

The health endpoint verifies database connectivity, Teams adapter initialization, and MCP server status. Docker and Kubernetes healthchecks point here — the pod is marked unhealthy if any MCP server is disconnected.

curl -s http://localhost:3978/api/health | python3 -m json.tool

curl -s https://your-domain.example.com/api/health | python3 -m json.tool

Expected response (all systems operational):

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

Metrics & Monitoring

Reva exposes metrics in two formats. No authentication is required for metrics endpoints.

Prometheus Format

GET /api/metrics    # text/plain; version=0.0.4

Scrape this endpoint with Prometheus, Grafana Agent, or any compatible collector. Key metrics:

JSON Format

GET /api/stats      # application/json

Same data as structured JSON — useful for dashboards, scripts, or ad-hoc inspection.

Support Bundle

The support bundle collects GDPR-safe diagnostic data for remote troubleshooting. It is designed for customer deployments where X-idra has no SSH access. Two collection methods are available: an API endpoint (when the application is running) and a shell script (when it is not).

Setup

Set a shared secret to enable the support bundle endpoint:

REVA_SUPPORT_SECRET=your-secret-here

docker compose up -d reva

kubectl patch configmap reva-env -n reva \
  --type merge -p '{"data":{"REVA_SUPPORT_SECRET":"your-secret-here"}}'
kubectl rollout restart deployment/reva -n reva

API Endpoint (Application Running)

Collect diagnostics as JSON or a downloadable ZIP archive:

# JSON response
curl -H "X-Support-Secret: $REVA_SUPPORT_SECRET" \
  https://your-domain.example.com/api/support-bundle

# ZIP archive (one file per section)
curl -H "X-Support-Secret: $REVA_SUPPORT_SECRET" \
  https://your-domain.example.com/api/support-bundle?format=zip \
  -o support-bundle.zip

What It Collects

The bundle runs 11 independent collectors. If one fails, the others still complete.

GDPR Sanitization

The support bundle is designed to be safe for sharing across organizational boundaries:

Offline Shell Script (Application Not Running)

When the application cannot start or the API is unreachable, use the shell script. It auto-detects whether the deployment uses Docker Compose or Kubernetes.

# Without API access (collects system info, logs, container status, DB stats)
./bin/support-bundle.sh

# With API access (also pulls the full API bundle)
REVA_SUPPORT_SECRET=your-secret ./bin/support-bundle.sh

The script produces a support-bundle-YYYY-MM-DD-HHMMSS.tar.gz archive in the project root directory containing:

• System information (OS, memory, disk, Docker/K8s version)
• Container/pod status and resource usage
• Application logs (last 1000 lines)
• Health check response (if reachable)
• Configuration with secrets masked
• Database statistics (row counts, connections, size)
• Full API bundle (if secret provided and API reachable)
• GDPR_NOTICE.txt documenting what was sanitized

Database Backups

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

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

# Automated: CronJob runs daily at 02:00 UTC
kubectl get cronjob db-backup -n reva

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

# Check backup logs
kubectl logs -n reva job/db-backup-manual

Log Management

# Follow Reva logs
docker compose logs -f reva

# Search for errors
docker compose logs reva | grep -i "error\|warning\|critical"

# Follow specific MCP server logs
docker compose logs -f reva 2>&1 | grep -i mcp

# Reva application
kubectl logs -n reva -l app=reva -c reva -f

# MCP sidecars
kubectl logs -n reva -l app=reva -c release-mcp -f
kubectl logs -n reva -l app=reva -c jira-mcp -f

# Previous pod logs (after crash)
kubectl logs -n reva -l app=reva -c reva --previous

# Search for errors
kubectl logs -n reva -l app=reva -c reva | grep -i "error\|warning"

Updates & Rollback

# Update version in .env
REVA_VERSION=1.0.5

# Pull new image and restart
docker compose pull reva
docker compose up -d reva

# Revert to previous version
REVA_VERSION=1.0.4
docker compose up -d reva

# Build new image and import
docker build -t reva:latest .
docker save reva:latest | sudo k3s ctr images import -

# Restart deployment
kubectl rollout restart deployment/reva -n reva

# Watch rollout
kubectl rollout status deployment/reva -n reva

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

# Check rollout history
kubectl rollout history deployment/reva -n reva