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.
KaireonAI supports three deployment paths depending on your needs:
Local Development Run on your machine with PostgreSQL and optional Redis. Best for development and evaluation.
Cloud (App Runner) Deploy to AWS App Runner with Supabase (PostgreSQL) and Upstash (Redis). Fully managed, no servers to maintain.
Kubernetes (Helm) Self-hosted on any Kubernetes cluster using the provided Helm chart. Full control over infrastructure.
Comparison 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-apiMain Next.js application (UI + API routes) kaireon-workerBackground job processing (pipelines, model retraining)
You push images to Amazon ECR and tag them with the git SHA plus latest:
docker build -t kaireon-api . docker tag kaireon-api:latest < YOUR_ACCOUNT_I D > .dkr.ecr. < REGIO N > .amazonaws.com/kaireon-api: $( git rev-parse --short HEAD ) docker push < YOUR_ACCOUNT_I D > .dkr.ecr. < REGIO N > .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_URLYes PostgreSQL connection string (postgresql://...) NEXTAUTH_SECRETYes (prod) Random secret for signing JWT sessions (min 32 chars in production) NEXTAUTH_URLYes (prod) Public URL of the application (e.g., https://your-domain.com)
Security (Required in Production) Variable Required Description JWT_SIGNING_SECRETYes (prod) Secret for signing API and OAuth tokens CONNECTOR_ENCRYPTION_KEYYes (prod) AES-256 key for encrypting connector credentials at rest CONNECTOR_ENCRYPTION_KEY_VERSIONNo Current key version (default: 1) CONNECTOR_ENCRYPTION_KEY_PREVIOUSNo Previous key for rotation WEBHOOK_SIGNING_SECRETYes (prod) HMAC secret for signing outbound webhooks API_KEY_PEPPERYes (prod) HMAC pepper for hashing API keys
Authentication Variable Required Description GOOGLE_CLIENT_IDNo Google OAuth client ID (for SSO) GOOGLE_CLIENT_SECRETNo Google OAuth client secret SES_FROM_EMAILNo Sender address for transactional emails (default: support@kaireonai.com) AWS_REGIONNo AWS region for SES (default: us-east-1)
Infrastructure Variable Required Description REDIS_URLNo Redis connection string for enrichment cache, rate limiting, circuit breakers, and event publishing ML_WORKER_URLNo URL of the ML Worker for AI features (e.g., http://localhost:8000) PG_POOL_MAXNo Max PostgreSQL pool connections (default: 50) PORTNo HTTP port (default: 3000)
Observability Variable Required Description LOG_LEVELNo Logging level: debug, info, warn, error (default: info) OTEL_EXPORTER_OTLP_ENDPOINTNo OpenTelemetry endpoint URL (enables distributed tracing when set) SLOW_API_THRESHOLD_MSNo Log slow API calls exceeding this threshold (default: 150)
Variable Required Description CORS_ALLOWED_ORIGINSYes (prod) Comma-separated allowed origins (must not be * in production) CSP_POLICYNo Custom Content Security Policy header CSP_DISABLEDNo Set true to disable CSP (not recommended in production)
Decisioning Tuning Variable Required Description MAX_ACTIVE_OFFERSNo Max offers loaded per recommendation (default: 5000) SCORING_FALLBACK_SCORENo Fallback score when model scoring fails (default: 0.5) MAX_MANDATORY_OFFERS_PER_DAYNo Daily limit on mandatory offer slots (default: 5) RETRAIN_EVERY_NNo Auto-retrain models every N outcomes (default: 100) ATTRIBUTION_TIMEOUT_MSNo Timeout for attribution lookups (default: 5000) RATE_LIMIT_TIERNo Rate limiting tier override
Tenant Configuration Variable Required Description SINGLE_TENANT_MODENo Set true to bypass tenant resolution (for single-tenant deploys) PLATFORM_OWNER_TENANT_IDNo Tenant ID for platform-level settings (default: default) INTERNAL_SERVICE_SECRETNo Shared secret for inter-service auth (falls back to NEXTAUTH_SECRET)
Worker Variable Required Description WORKER_CONCURRENCYNo BullMQ worker concurrency (default: 5) WORKER_METRICS_PORTNo Prometheus metrics port for worker (default: 9091)
Next Steps
Local Development Get started with a local PostgreSQL and Redis setup.
Cloud Deployment Deploy to AWS App Runner with Supabase and Upstash.
