> ## 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.

# Deployment

> How PR previews, staging, and production deployments work.

## 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`:

```
kair-cli deploy staging          # uses /configs/kair-voice/config.staging.yml on the deploy host
kair-cli deploy-frontend staging # KAIR_FRONTEND_HOST=staging.kair.is
```

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

| Config key | Required scheme |
| - | - |
| `database.url` | `postgres://…?sslmode=verify-full` |
| `redis.url` | `rediss://` |
| `rabbitmq.url` | `amqps://` |
| `s3.endpoint` | `https://` |
| `app.otel_exporter_otlp_endpoint` | `https://` (or loopback/docker-bridge) |
| `rag.neo4j_v2.url` | `neo4j+s://` or `bolt+s://` — **not** `bolt://`, `neo4j://`, or any `+ssc` variant |
| `ai_inference.*.base_url` | `https://` (exempt: loopback, `172.17/18.x.x`, `*.ts.net`, Tailscale CGNAT `100.64–127.x.x`) |
| `app.public_api_url` | `https://` |
| `google_calendar.redirect_uri` | `https://` |
| `recall.realtime_ws_base_url` | `wss://` (already enforced by config validation) |

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:

```yaml theme={null}
# traefik/dynamic/headers.yml
http:
  middlewares:
    secureHeaders:
      headers:
        stsSeconds: 31536000          # 1 year
        stsIncludeSubdomains: true
        stsPreload: true
        forceSTSHeader: true
        contentTypeNosniff: true
        frameDeny: true

  routers:
    kair-voice-api:
      middlewares:
        - secureHeaders
```

TLS ≥ 1.2 is enforced in the Traefik static config:

```yaml theme={null}
# traefik/traefik.yml
tls:
  options:
    default:
      minVersion: VersionTLS12
      cipherSuites:
        - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
        - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
        - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
        - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
```

### Tailscale ACL (database ports)

Only the `tag:main` and `tag:gpu` Tailscale device tags may reach database ports. Add to your Tailscale ACL policy:

```json theme={null}
{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:main", "tag:gpu"],
      "dst": ["tag:db:5432", "tag:db:6379", "tag:db:5672", "tag:db:7687"]
    }
  ]
}
```

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](https://docs.kair.is/platform/architecture.md#encryption-and-network-isolation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.