Akvo RAG is an intelligent question-answering system that enables users to chat with their own knowledge bases using Retrieval-Augmented Generation (RAG) technology.

While similar products exist, Akvo RAG focuses on flexibility and self-hosting. We built this to solve key challenges:

1. Easy Integration - Add RAG capabilities to any web application with minimal effort
2. Simplified Data Management - Easily add and manage knowledge bases with built-in data pipelines
3. Intelligent KB Selection - Automatically determine which knowledge bases to query for optimal responses
4. Full Self-Hosting - Deploy the entire stack (data pipeline, RAG, and LLM) on your own infrastructure

Akvo RAG supports two approaches for querying knowledge bases:

• Agent-Scoped Query (ASQ) Mode - The system automatically determines the most appropriate knowledge bases to query based on the user's question, ensuring the best possible response
• User-Scoped Query (USQ) Mode - Users manually select which knowledge bases to query, giving them direct control

The system defaults to USQ mode for simplicity, with ASQ mode available for more advanced, autonomous querying.

┌─────────────────────────────────────────────────────────────┐
│                         User/Client                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Frontend UI (Port 80)                     │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  Backend API (Port 8000)                     │
│                    • FastAPI                                 │
│                    • Authentication                          │
│                    • Business Logic                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                ┌──────────┴──────────┐
                ▼                     ▼
┌──────────────────────┐    ┌─────────────────────────┐
│  MCP Server          │    │  Job Queue              │
│  (Port 8100)         │    │  • RabbitMQ (5672)      │
│  • Knowledge Base    │    │  • Celery Workers       │
│  • Vector Search     │    │  • Flower UI (5555)     │
└──────────────────────┘    └─────────────────────────┘
           │
           ▼
┌──────────────────────┐
│  LLM Provider        │
│  • OpenAI            │
│  • DeepSeek          │
│  • Ollama (Local)    │
└──────────────────────┘

• Dynamic Prompt Service: Centralized prompt management with versioning and database storage
  • 👉 See full documentation: PROMPT_SERVICE.md
• RAG Evaluation: Built-in RAGAS metrics for pipeline performance evaluation
  • 👉 See full documentation: backend/RAG_evaluation/README.md
• Async Job Processing: Celery + RabbitMQ for scalable background tasks
• Multiple LLM Support: OpenAI, DeepSeek, and local Ollama deployment
• Monitoring Dashboard: Flower UI for real-time job tracking
• OpenAPI Integration: RESTful APIs for programmatic access

This project requires the MCP (Model Context Protocol) Server to function.

Without a running MCP server, RAG Web UI cannot:

• Query knowledge bases
• Process documents
• Generate RAG responses

You MUST set up the MCP server first before proceeding with RAG Web UI installation.

→ Jump to MCP Server Setup Instructions

Before starting, ensure you have:

• Docker & Docker Compose v2.0+
• Node.js 18+
• Python 3.9+
• 8GB+ RAM (16GB recommended)
• 10GB+ free disk space
• Ports 80, 5555, 5672, 8000, 8100 available

The MCP server provides the knowledge base query layer and must be running before starting RAG Web UI.

You have two options:

Option A: Local Installation

Follow the complete installation guide in the MCP server repository:

👉 Vector Knowledge Base MCP Server - Setup Guide

The MCP server runs on port 8100 by default.

Option B: Use Test Server (for quick testing only)

KNOWLEDGE_BASES_MCP=https://kb-mcp-server.akvotest.org/mcp/
KNOWLEDGE_BASES_API_KEY=supersecretapikey
KNOWLEDGE_BASES_API_ENDPOINT=https://kb-mcp-server.akvotest.org

⚠️ Note: The test server is for evaluation purposes only. For production, use your own MCP server installation.

curl http://localhost:8100/api/health

If this fails, troubleshoot the MCP server before proceeding.

git clone https://github.com/akvo/akvo-rag.git
cd akvo-rag

cp .env.example .env

Edit .env with your configuration. See the Complete Configuration Template below.

docker compose -f docker-compose.dev.yml up -d

# Watch the logs
docker compose logs -f

# Wait until you see messages like:
# "Application startup complete"
# "Uvicorn running on http://0.0.0.0:8000"

# Frontend UI
curl http://localhost:80

# Backend API Documentation
curl http://localhost:8000/docs

# Flower Dashboard (use browser)
open http://localhost:5555

# RabbitMQ Management (optional)
open http://localhost:15672

# Check backend logs for MCP connection
docker compose logs backend | grep -i mcp

# Should see: "MCP discovery manager finished successfully" or similar

docker compose ps

All services should show as "Up":

• frontend
• backend
• mysql
• rabbitmq
• celery-worker
• flower

Open your browser and navigate to:

http://localhost:80

The first admin account must be created using a seeder script:

# Run the admin user seeder
docker compose exec backend python -m app.seeder.seed_admin_user

# Follow the interactive prompts to:
# - Set admin email
# - Set admin username
# - Set admin password
# - Confirm admin password

Note: This admin account can later approve new user registrations.

Subsequent users can:

1. Click "Sign Up" or "Register"
2. Wait for admin approval via the admin dashboard
3. Once approved, log in with their credentials

1. Navigate to Knowledge Bases
2. Click Add New
3. Upload a test document (PDF, TXT, or DOCX)
4. Wait for processing to complete
5. View in Flower Dashboard (http://localhost:5555)

1. Go to Chat
2. Select your knowledge base
3. Ask a test question related to your document
4. Verify the response uses information from your document

The backend uses pytest for testing. All test commands run inside the Docker container and automatically install test dependencies as needed.

Ensure Docker containers are running:

Run All Tests

cd backend
./test.sh

Runs the complete test suite with verbose output.

Run Unit Tests Only

cd backend
./test-unit.sh

Runs only unit tests, excluding integration and end-to-end tests.

Run Tests in Watch Mode

cd backend
./test-watch.sh

Continuously runs tests when files change. Useful during development.

# Check all container status
docker compose ps

# View logs for specific service
docker compose logs backend
docker compose logs celery-worker
docker compose logs mysql

# Follow logs in real-time
docker compose logs -f

# Restart a specific service
docker compose restart backend

# Stop all services
docker compose down

# Stop and remove volumes (⚠️ deletes data)
docker compose down -v

RAG Web UI supports asynchronous background task processing using Celery, RabbitMQ, and Flower. This setup enables scalable execution of background jobs such as chat workflows, document embedding, and large knowledge base processing — without blocking FastAPI’s main thread.

NOTE: You can find Celery tasks code under app.tasks folder.

1. When an API endpoint (e.g. /api/apps/jobs) is called, a Celery task is queued into RabbitMQ.
2. The Celery worker process (running in its own container) listens for new jobs.
3. The worker executes the job asynchronously — for example, running a chat generation workflow or document embedding pipeline.
4. Job progress and results can be monitored in Flower or stored in your internal jobs database table.

This allows you to handle high-volume workloads, parallel processing, and non-blocking user responses.

NOTE: You don’t need to manually define CELERY_BROKER_URL or CELERY_RESULT_BACKEND. They are automatically constructed inside app/celery_app.py using the RabbitMQ configuration above.

Flower provides a web-based monitoring dashboard to observe workers and job progress.

Access Flower Dashboard Open: http://localhost:5555

Authentication Flower is password-protected to prevent unauthorized access. Use the credentials defined in your .env file:

Login via:

Username: admin
Password: admin

After logging in, you can:

1. View Registered Tasks
2. Track Task States
3. Monitor Workers
4. View Task History & Results

To verify task registration inside a running container:

docker compose exec celery-worker celery -A app.celery_app inspect registered

Expected output:

-> celery@worker-name: OK
    * tasks.execute_chat_job_task

Evaluate your RAG pipeline performance using RAGAS metrics with the built-in evaluation system.

# Start evaluation dashboard
./rag-evaluate

# Proper shutdown (prevents disk space issues)
./rag-evaluate-stop
# or use Ctrl-C (now handles cleanup automatically)

⚠️ Important: Always use proper shutdown methods. Improper termination can accumulate 1-2GB of Docker artifacts per session.

For complete evaluation documentation: backend/RAG_evaluation/README.md

This project is licensed under the Apache-2.0 License