> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Development

> Running the API, workers, and frontend locally.

## Prerequisites

* Rust (stable) — `rustup update stable`
* PostgreSQL running locally
* Redis running locally
* Neo4j running locally (only if HiRAG is enabled)
* Whisper model files in `api/ai_models/` (only if using local transcription)

## Config

Copy and edit the config:

```bash theme={null}
cp api/config.example.yml api/config.yml
# Edit database.url, redis.url, etc.
```

Minimum viable local `config.yml`:

```yaml theme={null}
database:
  url: "postgresql://postgres:postgres@localhost:5432/kair_voice"
app:
  base_url: "0.0.0.0:8000"
  uploads_dir: "./uploads"
redis:
  url: "redis://localhost:6379"
transcription:
  client: "local"
  realtime_model: "ai_models/ggml-base.bin"
  final_model: "ai_models/ggml-base.bin"
  nr_of_threads_for_transcription: 4
  uploads_dir: "./uploads"
```

Create the uploads directory:

```bash theme={null}
mkdir -p api/uploads
```

## Running the API

```bash theme={null}
cd api
cargo run --bin kair-voice-web-app
# API available at http://localhost:8000
# Swagger UI at http://localhost:8000/swagger
```

## Running workers

Workers run as separate processes. Open additional terminals:

```bash theme={null}
# Transcription worker
cd api
CONFIG_PATH=./config.yml cargo run --bin kair-voice-transcription-worker

# Summarisation worker
CONFIG_PATH=./config.yml cargo run --bin kair-voice-summarisation-worker

# HiRAG worker (optional)
CONFIG_PATH=./config.yml cargo run --bin kair-voice-hirag-worker
```

<Info>
  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`.
</Info>

## Running the web UI

```bash theme={null}
cd ui/web
pnpm install
pnpm dev
# Frontend at http://localhost:5173
```

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):

```bash theme={null}
cd api
docker compose up
```

## Database migrations

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

```bash theme={null}
cd api
cargo run --bin kair-voice-web-app -- --migrate-only
```

## Useful debug flags

```bash theme={null}
RUST_LOG=debug cargo run --bin kair-voice-web-app
RUST_LOG=debug CONFIG_PATH=./config.yml cargo run --bin kair-voice-transcription-worker
```

## Worker management (production)

On production servers, workers are managed via `manage-workers.sh` deployed to `/opt/kair-voice-workers/`:

```bash theme={null}
./manage-workers.sh start         # start all (3 transcription + 3 summarisation)
./manage-workers.sh stop          # graceful stop (30s timeout)
./manage-workers.sh restart       # stop + start
./manage-workers.sh status        # check running workers
./manage-workers.sh restart transcription   # restart one type only
```

Workers run on bare metal (not Docker) so deployments of the web server don't interrupt in-flight transcription jobs.