Install with Docker

Quickstart

✅ Status: core pipeline verified working. Ingest -> embed -> retrieve -> generate runs end-to-end via Docker Compose, including a clean fresh-clone test. See the Roadmap for what's next (PDF/DOCX support, alternative BYOK providers).

Fastest way to try it — one command checks Docker, clones the repo, and sets up .env for you:

curl -fsSL https://raw.githubusercontent.com/antonyrag/ragleap-core/main/install.sh | bash

(Windows users: run this in Git Bash, not Command Prompt or PowerShell.)

The script will pause after cloning and ask you to add your Gemini API key to .env — get a free one at aistudio.google.com/apikey, then re-run the same command.

Or, the manual way — better if you want to read the code before running anything:

git clone https://github.com/antonyrag/ragleap-core.git
cd ragleap-core
cp .env.example .env
# add your Gemini API key to .env
docker compose up --build -d

Requirements: Docker, Docker Compose, and a Gemini API key (embeddings currently always use Gemini). For chat you can use Gemini or any of 19 providers through LLM_PROVIDER, including a local Ollama model and any OpenAI-compatible endpoint.

Try it in 30 seconds — with the stack running, see examples/ for two verified, runnable scripts:

• examples/01_ingest_and_query.py — upload a document and ask a question via the API
• examples/02_test_channel_directly.py — test the WhatsApp/Telegram/Discord answering logic without real bot credentials

The installer script

This is install.sh from the repository at v0.7.5.

#!/usr/bin/env bash
set -euo pipefail

echo "🚀 RagLeap Core installer"
echo "   (Windows users: run this in Git Bash, not Command Prompt or PowerShell)"
echo ""

# 1. Check for Docker
if ! command -v docker &> /dev/null; then
    echo "❌ Docker is not installed."
    echo "   Install Docker Desktop first: https://www.docker.com/products/docker-desktop"
    exit 1
fi
echo "✅ Docker found"

# 2. Check Docker daemon is actually running
if ! docker info &> /dev/null; then
    echo "❌ Docker is installed but not running."
    echo "   Please start Docker Desktop, wait for it to fully load, then run this script again."
    exit 1
fi
echo "✅ Docker is running"

# 3. Clone the repo (skip if already present)
if [ -d "ragleap-core" ]; then
    echo "📁 ragleap-core/ already exists, using it"
    cd ragleap-core
else
    echo "📥 Cloning ragleap-core..."
    git clone https://github.com/antonyrag/ragleap-core.git
    cd ragleap-core
fi

# 4. Set up .env if it doesn't exist
if [ ! -f ".env" ]; then
    cp .env.example .env
    echo ""
    echo "⚠️  A .env file was created from .env.example."
    echo "   You need to add your GEMINI_API_KEY before continuing."
    echo "   Get a free key at: https://aistudio.google.com/apikey"
    echo ""
    echo "   Edit it now with: nano .env  (or any text editor)"
    echo "   Then re-run this script, or run: docker compose up --build -d"
    exit 0
else
    echo "✅ .env already exists"
fi

# 5. Build and start
echo "🐳 Building and starting RagLeap Core..."
docker compose up --build -d

echo ""
echo "✅ Done! Checking health..."
sleep 8
curl -sf http://localhost:8000/health && echo "" && echo "🎉 RagLeap Core is running at http://localhost:8000"
echo "   Try the interactive API docs: http://localhost:8000/docs"

docker-compose.yml

The stack the installer starts, from the same release.

# Security defaults: every published port is bound to 127.0.0.1 so a fresh install is NOT
# reachable from the internet. Docker's own firewall rules bypass UFW, so publishing a port
# as "5433:5432" opens it to the world even when ufw shows it closed. To reach a service
# from another machine use an SSH tunnel (ssh -L 8000:localhost:8000 host) or a reverse proxy
# that adds authentication. The API can be exposed deliberately with APP_BIND=0.0.0.0 in .env.
# The Postgres password comes from POSTGRES_PASSWORD in .env (default kept for compatibility;
# it only applies when the database volume is first created, see .env.example).

services:
  db:
    image: pgvector/pgvector:pg16
    restart: unless-stopped
    environment:
      POSTGRES_USER: ragleap
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-ragleap}
      POSTGRES_DB: ragleap_core
    ports:
      - "127.0.0.1:5433:5432"
    volumes:
      - ragleap_core_data:/var/lib/postgresql/data
      - ./db/schema.sql:/docker-entrypoint-initdb.d/01-schema.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ragleap -d ragleap_core"]
      interval: 5s
      timeout: 5s
      retries: 5

  app:
    build: .
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://ragleap:${POSTGRES_PASSWORD:-ragleap}@db:5432/ragleap_core
    extra_hosts:
      # Lets the container reach services on the host (e.g. a local Ollama
      # instance) via host.docker.internal, matching Docker Desktop's
      # built-in behavior which plain Linux Docker Engine doesn't have
      # by default. Requires Docker Engine >=20.10.
      - "host.docker.internal:host-gateway"
    ports:
      - "${APP_BIND:-127.0.0.1}:8000:8000"

  voice:
    profiles: ["voice", "full"]
    build: .
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://ragleap:${POSTGRES_PASSWORD:-ragleap}@db:5432/ragleap_core
    ports:
      - "127.0.0.1:8766:8765"
    command: ["python3", "-m", "channels.voice.server"]

  neo4j:
    profiles: ["graph", "full"]
    image: neo4j:5-community
    restart: unless-stopped
    environment:
      NEO4J_AUTH: neo4j/ragleapgraph
      NEO4J_PLUGINS: '[]'
    ports:
      - "127.0.0.1:7475:7474"
      - "127.0.0.1:7688:7687"
    volumes:
      - ragleap_core_neo4j_data:/data
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:7474 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 10

  redis:
    profiles: ["queue", "full"]
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "127.0.0.1:6380:6379"
    volumes:
      - ragleap_core_redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  worker:
    profiles: ["queue", "full"]
    build: .
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://ragleap:${POSTGRES_PASSWORD:-ragleap}@db:5432/ragleap_core
      REDIS_URL: redis://redis:6379/0
    extra_hosts:
      - "host.docker.internal:host-gateway"
    command: ["rq", "worker", "--url", "redis://redis:6379/0", "default"]
    # Scale horizontally with: docker compose up -d --scale worker=3
    # (only useful once REDIS_URL is set in .env - the app runs work
    # inline otherwise, and this container just idles waiting for jobs)

volumes:
  ragleap_core_data:
  ragleap_core_neo4j_data:
  ragleap_core_redis_data: