Ragz

Install on Linux

This is the reference install path for Ragz — every other platform guide reduces to this one. It runs the infrastructure services in Docker and the Ragz backend/frontend directly on the host, which is the fastest loop for development and the basis for a production deployment.

What you'll end up with

Postgres, Redis, Qdrant, MinIO, and LiteLLM running in Docker; a FastAPI backend, a Celery worker + beat scheduler, and a React frontend running natively — talking to each other over localhost.

Prerequisites

RequirementVersionUsed for
Docker Engine + Compose pluginrecentPostgres, Redis, Qdrant, MinIO, LiteLLM
Python3.12+Backend (FastAPI, Celery)
uvlatestPython dependency + venv management
Node.js20+Frontend (Vite/React)
pnpmlatestFrontend package management

Install Docker Engine (Ubuntu/Debian)

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker "$USER"
newgrp docker   # or log out/in to pick up the group change

Docker Engine ships the Compose plugin (docker compose, no hyphen) by default. Confirm both are working:

docker version
docker compose version

Install Python 3.12 + uv

curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.12

uv manages its own Python toolchain, so this works even if your distribution ships an older system Python.

Install Node 20+ and pnpm

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
corepack enable
corepack prepare pnpm@latest --activate

Already have Node?

If you already manage Node with nvm, fnm, or asdf, just make sure the active version is 20 or newer, then run corepack enable to get pnpm.

1. Clone the repository

git clone https://github.com/marketcalls/raghub.git
cd raghub

2. Start infrastructure

Bring up Postgres, Redis, Qdrant, MinIO, and LiteLLM with Docker Compose:

docker compose -f deploy/compose.yaml up -d

All services bind to 127.0.0.1 only. Give the containers a few seconds to pass their health checks before moving on:

docker compose -f deploy/compose.yaml ps

3. Backend

From backend/, install dependencies, run migrations, and create the first superadmin:

cd backend
uv sync
uv run alembic upgrade head
 
RAGZ_BOOTSTRAP_EMAIL=admin@example.com RAGZ_BOOTSTRAP_PASSWORD=changeme12345 \
  uv run python -m ragz.bootstrap

Bootstrap runs once

ragz.bootstrap creates the first superadmin account from RAGZ_BOOTSTRAP_EMAIL / RAGZ_BOOTSTRAP_PASSWORD. Use a real password (12+ characters) even in development — this account can create other organizations and admins.

Start the API:

uv run uvicorn --factory ragz.api.app:create_app --port 8000

4. Celery worker and beat scheduler

The worker handles document ingestion (parsing, embedding, OCR); beat syncs the model catalog on a schedule. Run each in its own terminal, from backend/:

# Worker
uv run celery -A ragz.worker.celery_app:celery_app worker -Q interactive,default -l info
# Beat scheduler
uv run celery -A ragz.worker.celery_app:celery_app beat -l info

Scanned PDFs need OCR

The first time a scanned/image-only PDF is ingested, the worker downloads ~90 MB of EasyOCR models to ~/.EasyOCR on the worker host. This happens once per host. Disable OCR entirely with RAGZ_OCR_ENABLED=false if you don't need it.

5. Frontend

From frontend/, with the backend already running (step 3 exposes the OpenAPI schema the client generator reads):

cd ../frontend
pnpm install
pnpm generate:api
pnpm dev

pnpm dev serves the app at http://localhost:5173.

6. First run

Open http://localhost:5173 and sign in with the bootstrap superadmin credentials from step 3. Then:

  1. Admin › Models — add a model (e.g. an OpenAI API key, or point at a local provider).
  2. Create a workspace.
  3. Upload a document — watch it move through parsing → embedding → ready.
  4. Chat — ask a question and get a cited answer.

You're running Ragz

From here, see Configuration to tune model placement and parsing, or RBAC to set up workspaces, groups, and custom roles before inviting other users.

Next steps