Installation

This guide will help you install and set up Easy RAG on your system.

Requirements

Python 3.11 or higher
Qdrant vector database (can be run via Docker)
4GB+ RAM recommended for large documents
Docker and Docker Compose (for containerized deployment)

System Dependencies

For PDF processing, you may need system libraries:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential

# macOS (using Homebrew)
brew install build-essential

Installation Methods

Method 1: Docker Compose (Recommended)

The easiest way to run Easy RAG is using Docker Compose, which sets up both the RAG API and Qdrant:

# Clone the repository
git clone <repository-url>
cd easy-rag

# Optionally create a .env file to customize configuration
# (see Configuration section below for all available options)
cp .env.example .env  # if .env.example exists
# Edit .env as needed

# Build and start services
docker compose up --build

# Run in background
docker compose up -d --build

The API will be available at http://localhost:8000 and Qdrant at http://localhost:6333.

Note: Docker Compose will automatically load environment variables from a .env file in the project root. You can also set environment variables directly in the docker-compose.yml file under the environment section for the rag service.

Method 2: Local Installation

For local development:

Clone the repository:
```
git clone <repository-url>
cd easy-rag
```

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Start Qdrant (using Docker):
```
docker compose up -d qdrant
```

Configure environment variables (optional):

Create a .env file in the project root. You can copy from .env.example if available, or create one with the following variables:

# Qdrant Configuration
QDRANT_HOST=localhost
QDRANT_GRPC_PORT=6334
COLLECTION_NAME=rag_store

# Embedding Model
EMBED_MODEL=Qwen/Qwen3-Embedding-0.6B

# Document Processing
CHUNK_SIZE=800
CHUNK_OVERLAP=100
BATCH_SIZE=100

# Retrieval Configuration
DEFAULT_K=8
MAX_K=20

# Server Configuration
HOST=0.0.0.0
PORT=8000

Run the application:

python -m src.main

Or using uvicorn directly:

uvicorn src.main:app --host 0.0.0.0 --port 8000

Configuration

All configuration options can be set via environment variables or a .env file. The application uses pydantic-settings which automatically loads variables from a .env file in the project root.

Environment Variables

You can configure Easy RAG using environment variables or a .env file. All settings are optional and have sensible defaults:

Qdrant Configuration: * QDRANT_HOST: Qdrant server host (default: localhost) * QDRANT_GRPC_PORT: Qdrant gRPC port (default: 6334) * COLLECTION_NAME: Name of the Qdrant collection to use (default: rag_store)

Embedding Model Configuration: * EMBED_MODEL: HuggingFace embedding model identifier (default: Qwen/Qwen3-Embedding-0.6B)

Document Processing Configuration: * CHUNK_SIZE: Document chunk size in characters (default: 800)

Larger values preserve more context but may slow processing

Recommended range: 500-1000

CHUNK_OVERLAP: Overlap between chunks in characters (default: 100) * Helps preserve context across chunk boundaries * Recommended: 10-20% of CHUNK_SIZE
BATCH_SIZE: Batch size for processing documents (default: 100) * Reduce if you encounter memory issues * Recommended range: 50-200

Retrieval Configuration: * DEFAULT_K: Default number of results to return (default: 8) * MAX_K: Maximum number of results that can be requested (default: 20)

Server Configuration: * HOST: API server host (default: 0.0.0.0) * PORT: API server port (default: 8000)

Creating a .env File

Create a .env file in the project root directory. Variable names are case-insensitive, so you can use uppercase, lowercase, or mixed case:

# Example .env file
QDRANT_HOST=localhost
QDRANT_GRPC_PORT=6334
COLLECTION_NAME=rag_store
EMBED_MODEL=Qwen/Qwen3-Embedding-0.6B
CHUNK_SIZE=800
CHUNK_OVERLAP=100
BATCH_SIZE=100
DEFAULT_K=8
MAX_K=20
HOST=0.0.0.0
PORT=8000

For Docker Compose deployments, you can also set these variables in the docker-compose.yml file under the environment section, or use a .env file that Docker Compose will automatically load.

Verification

After installation, verify everything is working:

Check API health:
```
curl http://localhost:8000/health
```
Access API documentation:

Open http://localhost:8000/docs in your browser to see the interactive API documentation.
Check Qdrant:

Open http://localhost:6333/dashboard to access Qdrant dashboard.

Troubleshooting

Common Issues

Port already in use: Change the port in .env or docker-compose.yml (note: filename is still docker-compose.yml)
Qdrant connection error: Ensure Qdrant is running and accessible
Memory errors with large PDFs: The batch processing should handle this, but you can reduce BATCH_SIZE if needed
Import errors: Make sure all dependencies are installed: pip install -r requirements.txt