Ragz

Install on Windows

The supported path on Windows is WSL2 + Ubuntu. Ragz's toolchain — uv, Celery with native parsing/OCR libraries, Docker — is developed and tested against Linux; WSL2 runs a real Ubuntu kernel and userspace, so the Linux install applies unmodified once you're inside it.

Native Windows is not supported

Running the backend directly under native Windows (PowerShell/cmd, no WSL) is not a supported path — Celery's native dependencies (Docling, EasyOCR, fastembed) and the container tooling assume a Linux environment. Use WSL2.

1. Enable WSL2

From an elevated PowerShell prompt:

wsl --install

This enables the WSL2 feature, installs the WSL2 kernel, and installs Ubuntu as the default distribution. Reboot if prompted, then launch Ubuntu from the Start menu to finish setup (it asks you to create a UNIX username and password on first launch).

If WSL was already installed and you just need Ubuntu:

wsl --install -d Ubuntu

Confirm you're on WSL2 (not the older WSL1):

wsl -l -v

2. Install Docker Desktop with the WSL2 backend

Install Docker Desktop for Windows and, during setup, ensure Use the WSL 2 based engine is enabled (default on current versions). Then, in Docker Desktop's Settings:

  • Resources › WSL Integration — enable integration for your Ubuntu distribution.

This lets the docker and docker compose commands you run inside Ubuntu talk to the same Docker engine Desktop manages on Windows — you do not need to install Docker separately inside WSL2.

Verify from inside Ubuntu

Open the Ubuntu terminal and run docker version and docker compose version. Both should succeed without sudo once WSL integration is enabled.

3. Follow the Linux install inside WSL2

From here, open the Ubuntu terminal (not PowerShell) and follow Install on Linux top to bottom:

  • Install prerequisites: Docker is already covered by Desktop's WSL integration above, so start with Python 3.12 + uv, then Node 20+ + pnpm, using the Ubuntu/Debian one-liners in that guide.
  • Clone the repository inside the Linux filesystem (e.g. ~/raghub, not /mnt/c/...) — builds and file watching are dramatically faster on the native ext4 filesystem than across the /mnt/c Windows interop boundary.
  • Run every subsequent step — docker compose -f deploy/compose.yaml up -d, the backend uv sync / alembic upgrade head / bootstrap / uvicorn, the Celery worker and beat scheduler, and the frontend pnpm install / pnpm generate:api / pnpm dev — from that Ubuntu shell.

Ports work the same

WSL2 forwards localhost between Windows and Ubuntu automatically, so http://localhost:5173 and http://localhost:8000 are reachable from your regular Windows browser once the frontend and backend are running inside WSL2 — no extra networking setup needed.

4. First run

Same as Linux: open http://localhost:5173 from your Windows browser, sign in with the bootstrap superadmin, add a model under Admin › Models, create a workspace, upload a document, and chat.

Next steps