Skip to main content

AI model volume

Workers that run whisper.cpp or rag (embedding) inference need access to model files. These are stored on an external Docker volume kair_voice_ai_models backed by /config/kair_voice_config/ai_models on the host. It is mounted read-only at /app/ai_models in all production workers and PR API stacks — see api/docker-compose.yml, api/docker-compose.staging.yml, and api/docker-compose.pr.yml.

GPU transcription worker

The production host has a GeForce 1080 attached, and transcription-worker in both api/docker-compose.yml and api/docker-compose.staging.yml builds from api/Dockerfile.transcription-cuda (whisper-rs compiled with the cuda feature) instead of the shared kair-voice image, with a deploy.resources.reservations.devices GPU reservation. Both stacks run on the same host and share the one GPU, so replicas is pinned to 1 — production’s config.yml keeps both the realtime_model and final_model whisper.cpp models resident in VRAM per process, and an 8GB card doesn’t have headroom for more than one at a time. No application code changes are needed to use the GPU: WhisperContextParameters::default() (api/crates/transcription/src/main.rs) uses the GPU automatically when the binary is built with --features cuda. One-time host setup (NVIDIA driver, NVIDIA Container Toolkit, nvidia-ctk runtime configure --runtime=docker) is required before docker compose up can hand the GPU to a container — see the comment block at the top of api/Dockerfile.transcription-cuda. kair-cli deploy staging/deploy production (api/crates/cli/src/main.rs) needs no changes: because the service now has its own build: block, docker compose up --build builds the CUDA image automatically, and --no-build (production promote) reuses whatever is already tagged kair-voice-transcription-cuda:latest. The promote-to-production workflow retags kair-voice-transcription-cuda:staging → :latest alongside the other images.

PR previews

When a PR is opened or updated, the CI workflow (.github/workflows/pr-review.yml) builds and deploys a preview stack:
  • Traefik routes pr{N}.kair.is to the web container only (traefik.enable=false on the PR API service).
  • The API is internal; the web container’s nginx proxies /api/... requests to it.
  • A per-PR config file /configs/kair-voice/config.staging.pr{N}.yml is generated on the self-hosted deploy runner from /configs/kair-voice/config.staging.yml (kair-cli deploy-pr, see api/crates/cli/src/main.rs) and bind-mounted into the API container at /app/config.yml. Operators must set recall.allowed_download_hosts on the staging template; kair-cli only injects stream_cutover_at when realtime is enabled without it (see platform/recall-calendar-integration).
  • Each preview gets its own empty Postgres database, kair_voice_pr_{N}. The API creates it on startup from database.maintenance_url (the staging URL, kept only in the generated preview config) and migrates that database alone. Cleanup drops it. Previews do not write to staging’s schema or seaql_migrations. The database role in the staging config needs CREATEDB.
  • Each preview runs its own summarisation and rag workers next to the API. They start once the API is healthy (database migrated). Transcription, moderator-agent and document workers are not part of a preview, so those jobs wait in the preview’s queues; use transcript upload to get content into a preview.
  • Each preview gets its own RabbitMQ vhost, kair_voice_pr_{N}, on the staging broker, so its jobs never reach staging’s workers. kair-cli deploy-pr rewrites rabbitmq.url to that vhost. With rabbitmq.management_url set (reachable from the deploy runner) it also creates the vhost with full permissions for the rabbitmq.url user, and cleanup deletes it. Write it as amqps://admin:pw@host:15671 (amqp(s) maps to http(s)) to use separate admin credentials just for creating/deleting the vhost; without credentials in it the rabbitmq.url user is used and needs the administrator tag. Without it the vhost must be created by hand (rabbitmqctl add_vhost + set_permissions), else the API fails at start-up with “vhost not found”.
  • Per-PR settings go in /configs/kair-voice/config.staging.pr{N}.overrides.yml, merged over the staging template on every deploy (mappings key by key) before the preview rewrites, so an override cannot point the preview at staging’s database or vhost. The generated config.staging.pr{N}.yml is rewritten on each push, so do not edit it by hand. Use the overrides file for, say, a preview’s own rag.neo4j_v2. Cleanup leaves it in place.
  • Redis and object storage stay shared with staging; so does Neo4j unless overridden.

Staging

Every push to main triggers an automatic staging deploy via .github/workflows/main.yml:
Staging and PR preview frontend builds set VITE_STAGING_MARKER=true, which swaps the browser tab favicon to /favicons/braid/favicon-staging.svg (braid mark + amber badge). Production, Innover, and 10x100 builds leave the flag off so promote cannot ship a badged tab from a retagged staging image — deploy-frontend production rebuilds. VITE_ENVIRONMENT (read from the server env files at build time) sets the Sentry environment tag: production for kair.is, Innover and 10x100, staging for staging, and PR previews are hardcoded to preview in api/docker-compose.pr.yml. Unset falls back to production.

Production promotion

Production is promoted manually via a GitHub Actions workflow run with action promote-to-production:
  1. Retags kair-voice:staging → kair-voice:latest, kair-voice-web:staging → kair-voice-web:latest, and kair-voice-transcription-cuda:staging → kair-voice-transcription-cuda:latest.
  2. Syncs config.yml on the host.
  3. Runs kair-cli deploy production --no-build and kair-cli deploy-frontend production (frontend rebuilds so production does not serve the staging-baked SPA flags such as VITE_STAGING_MARKER).
Traefik Host defaults to kair.is; override with KAIR_FRONTEND_HOST. Keep in sync with the kair-voice-app and kair-voice-web routers in api/docker-compose.yml.

WebSockets (/api/realtime)

The web app keeps one WebSocket per tab at /api/realtime. Anything between the browser and the API must pass Upgrade/Connection headers (the PR-preview nginx config does; Traefik does by default) and keep idle connections open past the server’s 25 s ping interval. Traefik v3’s 60 s entrypoint read timeout is fine because the pings keep the connection active; do not set it below ~30 s.

Subdomain API bundle

To serve the API from a different origin than the web app, set VITE_API_BASE_URL when building the web image — see ui/Dockerfile.

Org publish subdomains ({subdomain}.kair.is)

Public join/share links can use an org-specific host when organisations.public_subdomain is set (admin: /admin/organisations). This does not create per-org DNS records — ops must point a single wildcard at the platform:
  1. DNS: *.kair.is → same target as kair.is (Cloudflare proxied if applicable).
  2. TLS: Cloudflare Universal SSL on *.kair.is, or Traefik DNS-01 for a wildcard origin cert.
  3. Deploy API: api/docker-compose.yml includes HostRegexp /api routers (priority 50) for *.kair.is.
  4. Deploy production frontend: kair-cli deploy-frontend production merges ui/docker-compose.org-catchall.yml so unassigned *.kair.is hosts serve the kair.is SPA (priority 5). Innover/10x100/staging keep their exact-host routers at higher priority.
After deploy, verify curl -sI https://smoke-test.kair.is/ returns SPA HTML (200), not Traefik/Cloudflare 404/403.

Implementation

Deployment commands are implemented in api/crates/cli/src/main.rs.

Transport security (TLS ≥ 1.2, HSTS)

Every connection between services must use TLS in staging and production. The API and all workers call validate_transport_security at startup and fail immediately if any connection URL violates the rules below.

Required URL schemes

Development (app.env: development) is exempt from all checks.

HSTS and TLS ≥ 1.2 via Traefik

Add a secureHeaders middleware to your Traefik dynamic configuration:
TLS ≥ 1.2 is enforced in the Traefik static config:

Tailscale ACL (database ports)

Only the tag:main and tag:gpu Tailscale device tags may reach database ports. Add to your Tailscale ACL policy:
All other devices — including developer machines — must go through the API layer and cannot reach Postgres, Redis, RabbitMQ, or Neo4j directly. See Encryption and network isolation.