Install on macOS

The macOS install follows the same steps as Linux — infrastructure in Docker, backend and frontend running natively — with Homebrew for prerequisites and one required Celery flag.

Required: --pool=solo on the Celery worker

On macOS, Celery's default prefork pool crashes when the worker loads the native libraries used for parsing, OCR, and embeddings. Always start the worker with --pool=solo on macOS — it's called out explicitly below.

Prerequisites

Requirement	Version	Used for
Docker Desktop	recent	Postgres, Redis, Qdrant, MinIO, LiteLLM
Python	3.12+	Backend (FastAPI, Celery)
uv	latest	Python dependency + venv management
Node.js	20+	Frontend (Vite/React)
pnpm	latest	Frontend package management
Homebrew	latest	Installing the above

Install Docker Desktop

brew install --cask docker

Launch Docker Desktop once from /Applications so it finishes its first-run setup and starts the Docker daemon — the CLI commands below need it running. Confirm it's up:

docker version
docker compose version

Install Python 3.12 + uv

brew install uv
uv python install 3.12

uv manages its own Python toolchain independently of Homebrew's python@3.12 formula, so you don't need the latter.

Install Node 20+ and pnpm

brew install node
corepack enable
corepack prepare pnpm@latest --activate

1. Clone the repository

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

2. Start infrastructure

docker compose -f deploy/compose.yaml up -d
docker compose -f deploy/compose.yaml ps   # wait for services to report healthy

All services publish to 127.0.0.1 on non-default ports (Postgres on 55432, Redis on 56379, and so on) — see Docker for the full port table. This keeps Compose out of the way of anything else already listening locally.

3. Backend

From backend/:

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

This creates the first superadmin account from RAGZ_BOOTSTRAP_EMAIL / RAGZ_BOOTSTRAP_PASSWORD. Use a real password (12+ characters).

Start the API:

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

4. Celery worker and beat scheduler

Run each in its own terminal, from backend/. Note the --pool=solo flag on the worker — this is the one macOS-specific change from the Linux/production command:

# Worker — --pool=solo is required on macOS
uv run celery -A ragz.worker.celery_app:celery_app worker -Q interactive,default -l info --pool=solo

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

Why --pool=solo

The default prefork pool forks worker processes, and the native libraries Ragz loads for parsing/OCR/embeddings (Docling, EasyOCR, fastembed) don't survive that fork cleanly on macOS — the worker crashes shortly after startup. --pool=solo runs everything in a single process instead, which is stable. It's lower-throughput than prefork, which is fine for local dev; production Linux workers should not use it.

Scanned PDFs need OCR

The first scanned/image-only PDF ingested downloads ~90 MB of EasyOCR models to ~/.EasyOCR on the worker host. Disable with RAGZ_OCR_ENABLED=false if you don't need OCR.

5. Frontend

From frontend/, with the backend running:

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, sign in with the bootstrap superadmin from step 3, then:

Admin › Models — add a model.
Create a workspace.
Upload a document and watch it reach ready.
Chat — ask a question and get a cited answer.

You're running Ragz

Continue with Configuration or RBAC before inviting other users.