Ragz

Getting Started

Ragz is a self-hosted, multi-tenant agentic RAG platform: upload documents, ask questions, and get cited, streaming answers — with strict tenant isolation and document-level access control enforced from the first query. It runs on your own infrastructure: FastAPI + React + Qdrant + LiteLLM + Postgres, all under AGPL-3.0.

This guide gets a local instance running in about 10 minutes.

Prerequisites

Docker, Python 3.12 with uv, and Node 20+ with pnpm. See System Requirements for RAM and disk sizing before you commit to a setup.

1. Start infrastructure

Postgres, Qdrant, Redis, MinIO, LiteLLM, and the embeddings service all come up from the reference Compose file:

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

2. Run the backend

From backend/, install dependencies, run migrations, bootstrap the first superadmin account, and start the API:

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
 
uv run uvicorn --factory ragz.api.app:create_app --port 8000

In a second terminal (still from backend/), start the Celery worker that handles ingestion jobs. Add --pool=solo on macOS:

uv run celery -A ragz.worker.celery_app:celery_app worker -Q interactive,default -l info

In a third terminal, start the beat scheduler, which keeps the model catalog in sync:

uv run celery -A ragz.worker.celery_app:celery_app beat -l info

3. Run the frontend

From frontend/, install dependencies, generate the typed API client against your running backend, and start the dev server:

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

Set your KEK

Provider keys are stored with envelope AES-256-GCM encryption. The Key Encryption Key (KEK) is the one secret that lives outside the database — make sure it's set (RAGZ_KEK_FILE or equivalent) before you add real credentials.

First steps after login

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

StepWhereWhat happens
Add a modelAdmin → ModelsRegister a provider (e.g. an OpenAI key) or point at a local/OSS model via LiteLLM.
Create a workspaceWorkspacesWorkspaces scope documents, members, and access control within your org.
Upload documentsWorkspace → DocumentsPDF, DOCX, PPTX and more. Watch a job move parsing → embedding → ready.
ChatChatAsk a question. Answers stream in with citations — document, version, section, and page.

You're grounded

Ragz stays in no-answer mode when retrieval lacks sufficient grounding — it declines rather than hallucinates. That behavior is on by default.

Next steps

  • Review System Requirements before sizing a production install.
  • Follow a per-OS guide under Installation — start with Linux — for anything beyond a local dev stack.
  • Harden access with role-based permissions once you have more than one team in your org.