> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Deployment options
> How KaireonAI is delivered — hosted Cloud (the default), Dedicated single-tenant, or Enterprise on-prem under a commercial license.
KaireonAI is a proprietary, commercially licensed platform. There are three ways to run it:
**Hosted SaaS — the default.** We run KaireonAI for you on shared infrastructure. Sign up, pick a plan by decision volume, and go live — no servers to maintain. See [Licensing & Plans](/governance-security/licensing).
**Private cloud, single-tenant.** An isolated instance we operate for you, with dedicated compute, storage, and networking. For teams with data-isolation or compliance requirements. [Contact sales](mailto:sales@kaireonai.com).
**You run it, under a commercial license.** Deploy inside your own VPC or air-gapped cluster. Available on the Enterprise plan only — not free, not open, not self-serve. [Contact sales](mailto:sales@kaireonai.com).
The operational guides in this section (Docker Compose, Kubernetes / Helm, cloud infrastructure) apply to **Enterprise on-prem** deployments and internal development. Image and source access is provisioned as part of an Enterprise agreement. Most customers run on the fully hosted **Cloud** plan and never touch these.
## Enterprise on-prem topologies
Enterprise licensees can run KaireonAI in whichever topology fits their infrastructure:
Run on a workstation with PostgreSQL and optional Redis. For licensed development and evaluation.
Deploy to AWS App Runner with Supabase (PostgreSQL) and Upstash (Redis).
Deploy to any Kubernetes cluster using the provided Helm chart.
## Comparison of on-prem topologies
| | Local | Cloud (App Runner) | Kubernetes (Helm) |
| -------------- | ----------------------- | -------------------------- | --------------------- |
| **Best for** | Development, evaluation | Small-to-medium production | Enterprise production |
| **Database** | Local PostgreSQL | Supabase | Self-managed / RDS |
| **Cache** | Local Redis (optional) | Upstash | Self-managed Redis |
| **Scaling** | Single instance | Auto-scaling (App Runner) | HPA + custom policies |
| **Monitoring** | Dev tools | CloudWatch | Prometheus + Grafana |
| **TLS** | Not required | Auto (App Runner) | Ingress controller |
| **Setup time** | 5 minutes | 30 minutes | 1–2 hours |
## Docker Images
KaireonAI builds two Docker images:
| Image | Purpose |
| ---------------- | ------------------------------------------------------- |
| `kaireon-api` | Main Next.js application (UI + API routes) |
| `kaireon-worker` | Background job processing (pipelines, model retraining) |
The API `Dockerfile` lives in the `platform/` directory, so build from there. You push images to Amazon ECR and tag them with the git SHA plus `latest`:
```bash theme={null}
cd platform
docker build -t kaireon-api .
docker tag kaireon-api:latest .dkr.ecr..amazonaws.com/kaireon-api:$(git rev-parse --short HEAD)
docker push .dkr.ecr..amazonaws.com/kaireon-api:$(git rev-parse --short HEAD)
```
## Environment Variables
All deployment methods use the same core environment variables. The platform validates these at startup and will fail fast if required values are missing in production.
### Core (Required)
| Variable | Required | Description |
| ----------------- | ---------- | ------------------------------------------------------------------- |
| `DATABASE_URL` | Yes | PostgreSQL connection string (`postgresql://...`) |
| `NEXTAUTH_SECRET` | Yes (prod) | Random secret for signing JWT sessions (min 32 chars in production) |
| `NEXTAUTH_URL` | Yes (prod) | Public URL of the application (e.g., `https://your-domain.com`) |
### Security (Required in Production)
| Variable | Required | Description |
| ----------------------------------- | ---------- | -------------------------------------------------------- |
| `JWT_SIGNING_SECRET` | Yes (prod) | Secret for signing API and OAuth tokens |
| `CONNECTOR_ENCRYPTION_KEY` | Yes (prod) | AES-256 key for encrypting connector credentials at rest |
| `CONNECTOR_ENCRYPTION_KEY_VERSION` | No | Current key version (default: `1`) |
| `CONNECTOR_ENCRYPTION_KEY_PREVIOUS` | No | Previous key for rotation |
| `WEBHOOK_SIGNING_SECRET` | Yes (prod) | HMAC secret for signing outbound webhooks |
| `API_KEY_PEPPER` | Yes (prod) | HMAC pepper for hashing API keys |
### Authentication
| Variable | Required | Description |
| ---------------------- | -------- | -------------------------------------------------------------------------- |
| `GOOGLE_CLIENT_ID` | No | Google OAuth client ID (for SSO) |
| `GOOGLE_CLIENT_SECRET` | No | Google OAuth client secret |
| `SES_FROM_EMAIL` | No | Sender address for transactional emails (default: `support@kaireonai.com`) |
| `AWS_REGION` | No | AWS region for SES (default: `us-east-1`) |
### Infrastructure
| Variable | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `REDIS_URL` | No | Redis connection string for enrichment cache, rate limiting, circuit breakers, and event publishing |
| `ML_WORKER_URL` | No | URL of the ML Worker for AI features (e.g., `http://localhost:8000`) |
| `PG_POOL_MAX` | No | Max PostgreSQL pool connections (default: `50`) |
| **PORT** | No | HTTP port the platform process binds to (default: `3000`) |
### Observability
| Variable | Required | Description |
| ----------------------------- | -------- | ----------------------------------------------------------------- |
| `LOG_LEVEL` | No | Logging level: `debug`, `info`, `warn`, `error` (default: `info`) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | OpenTelemetry endpoint URL (enables distributed tracing when set) |
| `SLOW_API_THRESHOLD_MS` | No | Log slow API calls exceeding this threshold (default: `150`) |
### Security Headers
| Variable | Required | Description |
| ---------------------- | ---------- | --------------------------------------------------------------- |
| `CORS_ALLOWED_ORIGINS` | Yes (prod) | Comma-separated allowed origins (must not be `*` in production) |
| `CSP_POLICY` | No | Custom Content Security Policy header |
| `CSP_DISABLED` | No | Set `true` to disable CSP (not recommended in production) |
### Decisioning Tuning
| Variable | Required | Description |
| ------------------------ | -------- | ----------------------------------------------------- |
| `RETRAIN_EVERY_N` | No | Auto-retrain models every N outcomes (default: `100`) |
| `ATTRIBUTION_TIMEOUT_MS` | No | Timeout for attribution lookups (default: `5000`) |
| `RATE_LIMIT_TIER` | No | Rate limiting tier override |
The following decisioning defaults are currently compiled-in constants
rather than environment variables. To change one, edit the corresponding
constant in the circuit-breaker module or the decision-flow engine module
and redeploy:
| Default | Value |
| ------------------------------------------------- | ----- |
| Max offers loaded per recommendation | 5,000 |
| Fallback score when model scoring fails | 0.5 |
| Daily limit on mandatory offer slots per customer | 5 |
### Tenant Configuration
| Variable | Required | Description |
| -------------------------- | -------- | ---------------------------------------------------------------------- |
| `SINGLE_TENANT_MODE` | No | Set `true` to bypass tenant resolution (for single-tenant deploys) |
| `PLATFORM_OWNER_TENANT_ID` | No | Tenant ID for platform-level settings (default: `default`) |
| `INTERNAL_SERVICE_SECRET` | No | Shared secret for inter-service auth (falls back to `NEXTAUTH_SECRET`) |
### Worker
| Variable | Required | Description |
| --------------------- | -------- | ---------------------------------------------------- |
| `WORKER_CONCURRENCY` | No | BullMQ worker concurrency (default: `5`) |
| `WORKER_METRICS_PORT` | No | Prometheus metrics port for worker (default: `9091`) |
## Next Steps
Get started with a local PostgreSQL and Redis setup.
Deploy to AWS App Runner with Supabase and Upstash.