Skip to main content

Quick start (Windows, Docker-based dev-builder)

If you’re on Windows, don’t try to compile the Rust workspace natively — the -gnu toolchain drags in a vendored OpenSSL build (needs a full Perl with ExtUtils::MakeMaker/Pod::*, plus make on PATH) and hits an upstream whisper-rs-sys bug that only shows up on MinGW/GCC. None of that is worth fixing for a single Windows dev when CI/staging build on Linux anyway. Use the Ubuntu container instead:
Check the API came up: curl http://localhost:8000/api/health should return {"database":"ok","redis":"ok","status":"healthy"}. If any of the containers show Exited in docker ps -a (e.g. after a Docker Desktop restart), docker start them again — data persists in the container’s volumes.

Signing in without real email delivery

Local dev doesn’t send real magic-link emails. Request a sign-in from the UI as normal (enter the email, submit), then pull the token straight from Postgres instead of an inbox:
Then open http://localhost:5173/login/verify?token=<token> to complete sign-in. Dev-only — this reads the raw token straight out of the local database and only works because there’s no real mail transport configured locally; never do this against staging or production.

Prerequisites

  • Rust (stable) — rustup update stable
  • PostgreSQL running locally
  • Redis running locally
  • Neo4j running locally (only if rag.enabled is true; the topic graph needs rag.neo4j_v2)
  • Whisper model files in api/transcription_models/ (only if using local transcription)

Config

Copy and edit the config:
Minimum viable local config.yml:
Create the uploads directory:

Running the API

Running workers

Workers run as separate processes. Open additional terminals:
Whisper models are loaded once at worker startup. The base model (~1 GB) is sufficient for local dev. Download it with ./api/download-models.sh.

Running the web UI

Set VITE_API_BASE_URL=http://localhost:8000/api in ui/web/.env if the API is on a different port.

Running with Docker Compose

For a quick local setup (API + Redis only — workers run manually):

Database migrations

Migrations run automatically on API startup. To run them manually:

Useful debug flags

Worker management (production)

On production servers, workers are managed via manage-workers.sh deployed to /opt/kair-voice-workers/:
Workers run on bare metal (not Docker) so deployments of the web server don’t interrupt in-flight transcription jobs.