DevOps RAGQuick Start

Quick Start Guide - DevOps RAG ज्ञानकोश

Get up and running with DevOps RAG in 5 minutes. This guide covers the fastest path from zero to querying your first runbook.

Prerequisites

  • Docker installed
  • OpenAI API key
  • 2GB free disk space (for models and index)

🚀 5-Minute Setup

1. Pull the Docker Image

docker pull ghcr.io/gaurav21/devops-rag:latest

2. Run with Environment Variables

docker run -d \
  --name devops-rag \
  -p 8080:8080 \
  -e OPENAI_API_KEY=your_openai_api_key_here \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/runbooks:/app/runbooks \
  ghcr.io/gaurav21/devops-rag:latest

What this does:

  • Runs DevOps RAG on port 8080
  • Mounts ./data for persistent vector index
  • Mounts ./runbooks for your custom documentation
  • Uses 18 pre-loaded runbooks to get started

3. Verify Service is Running

curl http://localhost:8080/health

Expected Response:

{
  "status": "ok",
  "index_ready": true,
  "total_chunks": 45,
  "total_sources": 18
}

4. Your First Query

curl -X POST http://localhost:8080/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I fix CrashLoopBackOff in Kubernetes?",
    "top_k": 5
  }'

Expected Response:

{
  "answer": "To fix CrashLoopBackOff in Kubernetes:\n\n1. **Check Pod Logs**:\n   ```\n   kubectl logs <pod-name> -c <container>\n   kubectl logs <pod-name> --previous\n   ```\n\n2. **Describe the Pod**:\n   ```\n   kubectl describe pod <pod-name>\n   ```\n\n3. **Common Causes**:\n   - Application crashes immediately after startup\n   - Misconfigured readiness/liveness probes\n   - Insufficient resources (CPU/memory)\n   - Missing config files or secrets\n\n4. **Solutions**:\n   - Fix application startup issues\n   - Adjust probe settings (initialDelaySeconds, timeoutSeconds)\n   - Increase resource requests/limits\n   - Verify ConfigMaps and Secrets are mounted correctly",
  "sources": ["01-kubernetes-troubleshooting.md"],
  "citations": [
    {
      "source": "01-kubernetes-troubleshooting.md",
      "relevance": 0.8234,
      "excerpt": "CrashLoopBackOff indicates that a container is crashing repeatedly...",
      "chunk_id": "01-kubernetes-troubleshooting.md:3"
    }
  ],
  "context_chunks": 5,
  "top_score": 0.8234,
  "avg_score": 0.7156
}

5. Access the React UI

Open your browser to http://localhost:8080

The UI provides:

  • Chat interface with markdown rendering
  • Source citations with relevance scores
  • Sample queries to get started
  • Runbook browser showing all loaded documentation

📝 Add Your Own Runbooks

Option 1: Volume Mount (Recommended)

  1. Create a runbooks directory:
mkdir -p ./custom-runbooks
  1. Add your markdown files:
echo "# My Custom Runbook\n\nHow to deploy our app..." > ./custom-runbooks/deployment.md
  1. Run with custom runbooks:
docker run -d \
  --name devops-rag \
  -p 8080:8080 \
  -e OPENAI_API_KEY=your_key \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/custom-runbooks:/app/runbooks \
  ghcr.io/gaurav21/devops-rag:latest

Option 2: Copy into Running Container

# Copy files into running container
docker cp ./my-runbook.md devops-rag:/app/runbooks/
 
# Re-ingest (triggers automatic re-indexing)
docker exec devops-rag python cli.py ingest

🧪 Test Your Setup

# Check loaded sources
curl http://localhost:8080/sources
 
# Get index statistics  
curl http://localhost:8080/stats
 
# Test with a complex query
curl -X POST http://localhost:8080/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the steps for rolling back a failed deployment?",
    "verbose": true
  }'

⚡ Next Steps

🔧 Troubleshooting

Container Won’t Start

# Check logs
docker logs devops-rag
 
# Common issues:
# 1. Missing OPENAI_API_KEY
# 2. Port 8080 already in use
# 3. Insufficient disk space

Index Not Building

# Force re-index
docker exec devops-rag python cli.py ingest
 
# Check if runbooks directory exists
docker exec devops-rag ls -la /app/runbooks/

API Not Responding

# Check service health
curl http://localhost:8080/health
 
# Verify API is listening
docker exec devops-rag netstat -tlnp | grep 8080

Performance Issues

  • Slow queries: Reduce top_k from 5 to 3
  • High memory: Use smaller chunk size (256 instead of 512)
  • API timeouts: Increase container memory limit

Need Help? Check the troubleshooting section or review the tuning guide for performance optimization.

OverviewAPI Reference