AI model volume
Workers that run whisper.cpp or rag (embedding) inference need access to model files. These are stored on an external Docker volumekair_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, andtranscription-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.isto the web container only (traefik.enable=falseon 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}.ymlis generated on the self-hosted deploy runner from/configs/kair-voice/config.staging.yml(kair-cli deploy-pr, seeapi/crates/cli/src/main.rs) and bind-mounted into the API container at/app/config.yml. Operators must setrecall.allowed_download_hostson the staging template;kair-clionly injectsstream_cutover_atwhen realtime is enabled without it (seeplatform/recall-calendar-integration). - Each preview gets its own empty Postgres database,
kair_voice_pr_{N}. The API creates it on startup fromdatabase.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 orseaql_migrations. The database role in the staging config needsCREATEDB. - 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-prrewritesrabbitmq.urlto that vhost. Withrabbitmq.management_urlset (reachable from the deploy runner) it also creates the vhost with full permissions for therabbitmq.urluser, and cleanup deletes it. Write it asamqps://admin:pw@host:15671(amqp(s)maps tohttp(s)) to use separate admin credentials just for creating/deleting the vhost; without credentials in it therabbitmq.urluser is used and needs theadministratortag. 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 generatedconfig.staging.pr{N}.ymlis rewritten on each push, so do not edit it by hand. Use the overrides file for, say, a preview’s ownrag.neo4j_v2. Cleanup leaves it in place. - Redis and object storage stay shared with staging; so does Neo4j unless overridden.
Staging
Every push tomain triggers an automatic staging deploy via .github/workflows/main.yml:
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 actionpromote-to-production:
- Retags
kair-voice:staging→kair-voice:latest,kair-voice-web:staging→kair-voice-web:latest, andkair-voice-transcription-cuda:staging→kair-voice-transcription-cuda:latest. - Syncs
config.ymlon the host. - Runs
kair-cli deploy production --no-buildandkair-cli deploy-frontend production(frontend rebuilds so production does not serve the staging-baked SPA flags such asVITE_STAGING_MARKER).
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, setVITE_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:
- DNS:
*.kair.is→ same target askair.is(Cloudflare proxied if applicable). - TLS: Cloudflare Universal SSL on
*.kair.is, or Traefik DNS-01 for a wildcard origin cert. - Deploy API:
api/docker-compose.ymlincludesHostRegexp/apirouters (priority 50) for*.kair.is. - Deploy production frontend:
kair-cli deploy-frontend productionmergesui/docker-compose.org-catchall.ymlso unassigned*.kair.ishosts serve the kair.is SPA (priority 5). Innover/10x100/staging keep their exact-host routers at higher priority.
curl -sI https://smoke-test.kair.is/ returns SPA HTML (200), not Traefik/Cloudflare 404/403.
Implementation
Deployment commands are implemented inapi/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 callvalidate_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 asecureHeaders middleware to your Traefik dynamic configuration:
Tailscale ACL (database ports)
Only thetag:main and tag:gpu Tailscale device tags may reach database ports. Add to your Tailscale ACL policy: