Configuration Reference

Complete reference for all environment variables used by the KaireonAI platform.

1. Quick Reference

Variable	Required	Default	Category
`DATABASE_URL`	Yes	—	Database
`REDIS_URL`	No	— (cache disabled)	Cache
`NEXTAUTH_URL`	Yes	—	Authentication
`NEXTAUTH_SECRET`	Yes	—	Authentication
`JWT_SIGNING_SECRET`	Yes	—	Authentication
`CONNECTOR_ENCRYPTION_KEY`	Yes	—	Security
`LOG_LEVEL`	No	`info`	Observability
`NODE_ENV`	No	`development`	Runtime
`WORKER_CONCURRENCY`	No	`4`	Workers
`EVENT_PUBLISHER`	No	`memory`	Integration
`CACHE_STORE`	No	`memory`	Integration
`INTERACTION_STORE`	No	`postgres`	Integration
`SEARCH_INDEX`	No	`postgres`	Integration
`OTEL_EXPORTER_OTLP_ENDPOINT`	No	—	Observability

2. Database

DATABASE_URL

PostgreSQL connection string used by Prisma via the @prisma/adapter-pg driver adapter.

Property	Value
Required	Yes
Default	—
Format	`postgresql://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=require`
Example	`postgresql://kaireon:s3cret@db.example.com:5432/kaireon_prod?sslmode=require`

Notes:

In Prisma 7, this value is read from prisma.config.ts, not from the schema.prisma datasource block.
For RDS deployments, append ?sslmode=require and optionally &sslrootcert=/app/certs/rds-ca.pem.
Use IAM database authentication in production where possible.
Connection pooling is handled by the pg adapter; set connection_limit in the connection string if needed.

REDIS_URL

Redis connection string for caching. Optional — the platform runs without Redis. Cache can also be configured from Settings > Integrations UI.

Property	Value
Required	No
Default	— (cache disabled when not set)
Format	`redis://[:PASSWORD@]HOST:PORT[/DB]` or `rediss://` for TLS
Example	`rediss://:authtoken@cache.example.com:6379/0`

Notes:

Use rediss:// (double s) for TLS connections to ElastiCache.
Alternatively, configure cache from Settings > Integrations UI with full TLS, Sentinel, and Cluster support.
For ElastiCache cluster mode, use the configuration endpoint.

3. Authentication

NEXTAUTH_URL

The canonical URL of the KaireonAI application. Used by NextAuth.js for callback URLs and CSRF protection.

Property	Value
Required	Yes
Default	—
Format	Full URL with protocol
Example	`https://app.kaireon.example.com`

Notes:

Must match the domain configured in your OAuth provider.
Do not include a trailing slash.
In development, use http://localhost:3000.

NEXTAUTH_SECRET

Secret used to encrypt NextAuth.js session tokens and CSRF tokens.

Property	Value
Required	Yes
Default	—
Format	Random string, minimum 32 characters
Example	`a1b2c3d4e5f6...` (use `openssl rand -base64 32` to generate)

Notes:

Must be identical across all application replicas.
Rotate every 180 days. See the security hardening guide for rotation procedures.
Store in AWS Secrets Manager, never in source control.

JWT_SIGNING_SECRET

Secret used to sign and verify JWT tokens for API authentication.

Property	Value
Required	Yes
Default	—
Format	Random string, minimum 32 characters
Example	`x9y8z7w6v5u4...` (use `openssl rand -base64 32` to generate)

Notes:

Used for service-to-service authentication and API key validation.
Must differ from NEXTAUTH_SECRET.
Support dual-key validation during rotation: the application accepts tokens signed with either the current or previous key.

4. Security

CONNECTOR_ENCRYPTION_KEY

AES-256 encryption key used to encrypt connector credentials (database passwords, API keys, OAuth tokens) at rest.

Property	Value
Required	Yes
Default	—
Format	32-byte hex string (64 hex characters) or base64-encoded 32 bytes
Example	`0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef`

Notes:

Used by the connector registry to encrypt sensitive configuration fields before storing in PostgreSQL.
Rotation requires re-encrypting all existing connector credentials. See the security hardening guide.
Generate with: openssl rand -hex 32.

5. Runtime

NODE_ENV

Node.js environment identifier. Controls Next.js build behavior, logging verbosity, and debug features.

Property	Value
Required	No
Default	`development`
Allowed	`development`, `production`, `test`
Example	`production`

Notes:

Set to production in all deployed environments (staging, production).
In development mode, Next.js enables hot module replacement and verbose error pages.
In production mode, error details are hidden from responses for security.

LOG_LEVEL

Controls the minimum severity level for application log output.

Property	Value
Required	No
Default	`info`
Allowed	`error`, `warn`, `info`, `debug`, `trace`
Example	`info`

Notes:

Use debug or trace only for troubleshooting. These levels generate high log volume.
In production, info is recommended. Use warn if log costs are a concern.
Log output is structured JSON when NODE_ENV=production.

WORKER_CONCURRENCY

Maximum number of concurrent pipeline tasks a single worker pod processes.

Property	Value
Required	No
Default	`4`
Format	Positive integer
Example	`8`

Notes:

Increase for CPU-heavy transform workloads on larger instances.
Each concurrent task consumes approximately 256 MiB of memory. Ensure the pod memory limit accommodates WORKER_CONCURRENCY * 256 MiB plus overhead.
Set to 1 for debugging pipeline issues in isolation.

6. Integration Backends

These variables control which backing services KaireonAI uses for event publishing, caching, interaction storage, and search. All default to PostgreSQL or in-process implementations — no external infrastructure is required. Infrastructure can also be configured from Settings > Integrations UI, which overrides these env vars.

UI-first configuration: All infrastructure backends can be configured from Settings > Integrations with full support for TLS, authentication (including AWS IAM roles), and advanced options. Environment variables serve as fallbacks.

EVENT_PUBLISHER

The event publishing backend for domain events (offer served, decision made, pipeline completed).

Property	Value
Required	No
Default	`none` (in-process)
Allowed	`none`, `kafka`, `redpanda`
Example	`kafka`

Related variables by backend:

Backend	Additional Variables
`none`	None. Events are processed in-process.
`kafka`	`KAFKA_BROKERS`, `KAFKA_TOPIC_PREFIX`, `KAFKA_SASL_USERNAME`, `KAFKA_SASL_PASSWORD`
`redpanda`	Same as Kafka (Kafka-compatible protocol)

For AWS MSK with IAM authentication, configure from Settings > Integrations UI (supports IRSA role-based auth).

CACHE_STORE

The caching backend for decision results, feature vectors, and session data.

Property	Value
Required	No
Default	`none` (no caching)
Allowed	`none`, `redis`, `dragonfly`
Example	`redis`

Notes:

none means no caching — all reads hit PostgreSQL directly. Suitable for low-traffic deployments.
redis/dragonfly requires REDIS_URL or UI configuration. Recommended for multi-replica deployments or >1000 req/s.
Full TLS, Sentinel, and Cluster mode can be configured from Settings > Integrations UI.

INTERACTION_STORE

The storage backend for customer interaction history used by scoring engines.

Property	Value
Required	No
Default	`pg` (PostgreSQL)
Allowed	`pg`, `scylla`, `cassandra`
Example	`scylla`

Related variables by backend:

Backend	Additional Variables
`pg`	`DATABASE_URL` (shared)
`scylla`	Configure from Settings > Integrations UI (contact points, TLS, etc.)
`cassandra`	Same as ScyllaDB (compatible protocol)

SEARCH_INDEX

The backend for full-text search across offers, blueprints, and connectors.

Property	Value
Required	No
Default	`pg` (PostgreSQL tsvector)
Allowed	`pg`, `opensearch`
Example	`opensearch`

Related variables by backend:

Backend	Additional Variables
`pg`	`DATABASE_URL` (shared, uses `tsvector` columns)
`opensearch`	`OPENSEARCH_URL`, `OPENSEARCH_INDEX_PREFIX`, or configure from UI with AWS IAM auth

Note on Sections 7-11: The default Helm configmap.yaml only passes through OTEL_EXPORTER_OTLP_ENDPOINT, CLOUDWATCH_LOG_GROUP, and CLOUDWATCH_REGION. All other variables in sections 7-11 require manual addition to your Helm values override or direct environment variable injection. They are documented here for teams integrating with these services.

7. Observability

OTEL_EXPORTER_OTLP_ENDPOINT

The OpenTelemetry Collector endpoint for exporting traces, metrics, and logs.

Property	Value
Required	No
Default	— (telemetry disabled when not set)
Format	URL with protocol and port
Example	`http://otel-collector.observability:4318`

Notes:

Uses the OTLP/HTTP protocol by default (port 4318). For gRPC, use port 4317 and set OTEL_EXPORTER_OTLP_PROTOCOL=grpc.
When set, the application emits traces for all API requests, database queries, and pipeline executions.
Pair with the OTEL_SERVICE_NAME variable to set the service name in trace data.

OTEL_EXPORTER_OTLP_ENDPOINT is the only OTEL variable included in the default Helm configmap. The following OTEL variables require manual configuration:

OTEL_SERVICE_NAME

Service name reported in telemetry data.

Property	Value
Required	No
Default	`kaireon-app`
Format	String
Example	`kaireon-app-production`

OTEL_EXPORTER_OTLP_PROTOCOL

Protocol used to export telemetry data.

Property	Value
Required	No
Default	`http/protobuf`
Allowed	`http/protobuf`, `grpc`
Example	`grpc`

OTEL_TRACES_SAMPLER

Controls trace sampling strategy to manage telemetry volume.

Property	Value
Required	No
Default	`parentbased_traceidratio`
Allowed	`always_on`, `always_off`, `traceidratio`, `parentbased_traceidratio`
Example	`parentbased_traceidratio`

OTEL_TRACES_SAMPLER_ARG

Sampling ratio argument when using a ratio-based sampler.

Property	Value
Required	No
Default	`0.1` (10% of traces)
Format	Float between 0.0 and 1.0
Example	`0.05`

Notes:

In production, sample 5-10% of traces to control costs.
Set to 1.0 in staging or when debugging specific issues.

8. Kafka Integration (Manual Config)

These variables are required only when EVENT_PUBLISHER=kafka.

KAFKA_BROKERS

Comma-separated list of Kafka broker addresses.

Property	Value
Required	When `EVENT_PUBLISHER=kafka`
Default	—
Format	`host1:port,host2:port`
Example	`kafka-1.example.com:9092,kafka-2.example.com:9092`

KAFKA_TOPIC_PREFIX

Prefix applied to all Kafka topic names to support multi-tenant or multi-environment deployments.

Property	Value
Required	No
Default	`kaireon`
Format	String (alphanumeric and hyphens)
Example	`kaireon-prod`

Resulting topics: {prefix}.decisions, {prefix}.events, {prefix}.pipeline-runs.

KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

SASL/PLAIN credentials for authenticating with the Kafka cluster.

Property	Value
Required	When Kafka requires authentication
Default	—
Format	String
Example	`kaireon-producer` / `s3cret`

9. AWS Integration (Manual Config)

AWS_REGION

AWS region for SDK calls (SNS, DynamoDB, Secrets Manager, S3).

Property	Value
Required	When using AWS-backed integrations
Default	`us-east-1`
Format	AWS region code
Example	`us-west-2`

SNS_TOPIC_ARN

ARN of the SNS topic for event publishing when EVENT_PUBLISHER=sns.

Property	Value
Required	When `EVENT_PUBLISHER=sns`
Default	—
Format	ARN
Example	`arn:aws:sns:us-east-1:123456789012:kaireon-events`

DYNAMODB_TABLE_NAME

DynamoDB table name for interaction storage when INTERACTION_STORE=dynamodb.

Property	Value
Required	When `INTERACTION_STORE=dynamodb`
Default	`kaireon-interactions`
Format	String
Example	`kaireon-interactions-prod`

10. Search Integration (Manual Config)

OPENSEARCH_URL

OpenSearch cluster endpoint when SEARCH_INDEX=opensearch.

Property	Value
Required	When `SEARCH_INDEX=opensearch`
Default	—
Format	URL with protocol
Example	`https://search.example.com:9200`

OPENSEARCH_INDEX_PREFIX

Prefix for OpenSearch index names.

Property	Value
Required	No
Default	`kaireon`
Format	String
Example	`kaireon-prod`

11. Analytics Integration (Manual Config)

CLICKHOUSE_URL

ClickHouse connection URL when INTERACTION_STORE=clickhouse.

Property	Value
Required	When `INTERACTION_STORE=clickhouse`
Default	—
Format	`http://HOST:PORT` or `https://HOST:PORT`
Example	`https://clickhouse.example.com:8443`

CLICKHOUSE_DATABASE

ClickHouse database name.

Property	Value
Required	When `INTERACTION_STORE=clickhouse`
Default	`kaireon`
Format	String
Example	`kaireon_prod`

12. Example .env Files

Development

# Database
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kaireon_dev

# Auth
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<generate with: openssl rand -base64 32>
JWT_SIGNING_SECRET=<generate with: openssl rand -base64 64>

# Security
CONNECTOR_ENCRYPTION_KEY=<generate with: openssl rand -hex 32>

# Runtime
NODE_ENV=development
LOG_LEVEL=debug

# Backends (all in-process/local)
EVENT_PUBLISHER=memory
CACHE_STORE=memory
INTERACTION_STORE=postgres
SEARCH_INDEX=postgres

Production (Minimal — PostgreSQL Only)

# Database (from Secrets Manager via ESO)
DATABASE_URL=postgresql://kaireon:ROTATED_PASSWORD@kaireon-db.abc123.us-east-1.rds.amazonaws.com:5432/kaireon?sslmode=require

# Auth (from Secrets Manager via ESO)
NEXTAUTH_URL=https://app.kaireon.example.com
NEXTAUTH_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
JWT_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER

# Security (from Secrets Manager via ESO)
CONNECTOR_ENCRYPTION_KEY=ROTATED_KEY_FROM_SECRETS_MANAGER

# Runtime
NODE_ENV=production
LOG_LEVEL=info
WORKER_CONCURRENCY=8

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability:4318
OTEL_SERVICE_NAME=kaireon-app-production
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.05

Note: Infrastructure backends (Cache, Event Bus, Search, Interaction Store) are configured from Settings > Integrations UI. No env vars needed — the UI supports full TLS, AWS IAM roles, and advanced configuration. AWS services use IAM roles (IRSA) by default when running on EKS.

Production (Full Infrastructure via Env Vars)

If you prefer env vars over UI configuration:

# Database (from Secrets Manager via ESO)
DATABASE_URL=postgresql://kaireon:ROTATED_PASSWORD@kaireon-db.abc123.us-east-1.rds.amazonaws.com:5432/kaireon?sslmode=require

# Cache (optional — configure via UI or env var)
REDIS_URL=rediss://:AUTH_TOKEN@kaireon-cache.abc123.use1.cache.amazonaws.com:6379/0

# Auth (from Secrets Manager via ESO)
NEXTAUTH_URL=https://app.kaireon.example.com
NEXTAUTH_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER
JWT_SIGNING_SECRET=ROTATED_SECRET_FROM_SECRETS_MANAGER

# Security (from Secrets Manager via ESO)
CONNECTOR_ENCRYPTION_KEY=ROTATED_KEY_FROM_SECRETS_MANAGER

# Runtime
NODE_ENV=production
LOG_LEVEL=info
WORKER_CONCURRENCY=8

# Backends (all optional — can be configured from Settings > Integrations UI instead)
EVENT_PUBLISHER=kafka
CACHE_STORE=redis
INTERACTION_STORE=pg
SEARCH_INDEX=opensearch

# Kafka / AWS MSK (IAM auth recommended — configure via UI for IRSA support)
KAFKA_BROKERS=kafka-1.example.com:9092,kafka-2.example.com:9092,kafka-3.example.com:9092
KAFKA_TOPIC_PREFIX=kaireon-prod
KAFKA_SASL_USERNAME=kaireon-producer
KAFKA_SASL_PASSWORD=FROM_SECRETS_MANAGER

# AWS
AWS_REGION=us-east-1

# Search (AWS OpenSearch with IAM auth recommended — configure via UI for IRSA support)
OPENSEARCH_URL=https://search.example.com:9200
OPENSEARCH_INDEX_PREFIX=kaireon-prod

# Observability
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability:4318
OTEL_SERVICE_NAME=kaireon-app-production
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.05

Get Started

Deploy & Operate

Runbooks

Data Platform

Decisioning Studio

Execute & Optimize

Intelligence

Platform & Security

Integrations

​1. Quick Reference

​2. Database

​DATABASE_URL

​REDIS_URL

​3. Authentication

​NEXTAUTH_URL

​NEXTAUTH_SECRET

​JWT_SIGNING_SECRET

​4. Security

​CONNECTOR_ENCRYPTION_KEY

​5. Runtime

​NODE_ENV

​LOG_LEVEL

​WORKER_CONCURRENCY

​6. Integration Backends

​EVENT_PUBLISHER

​CACHE_STORE

​INTERACTION_STORE

​SEARCH_INDEX

​7. Observability

​OTEL_EXPORTER_OTLP_ENDPOINT

​OTEL_SERVICE_NAME

​OTEL_EXPORTER_OTLP_PROTOCOL

​OTEL_TRACES_SAMPLER

​OTEL_TRACES_SAMPLER_ARG

​8. Kafka Integration (Manual Config)

​KAFKA_BROKERS

​KAFKA_TOPIC_PREFIX

​KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

​9. AWS Integration (Manual Config)

​AWS_REGION

​SNS_TOPIC_ARN

​DYNAMODB_TABLE_NAME

​10. Search Integration (Manual Config)

​OPENSEARCH_URL

​OPENSEARCH_INDEX_PREFIX

​11. Analytics Integration (Manual Config)

​CLICKHOUSE_URL

​CLICKHOUSE_DATABASE

​12. Example .env Files

​Development

​Production (Minimal — PostgreSQL Only)

​Production (Full Infrastructure via Env Vars)

1. Quick Reference

2. Database

DATABASE_URL

REDIS_URL

3. Authentication

NEXTAUTH_URL

NEXTAUTH_SECRET

JWT_SIGNING_SECRET

4. Security

CONNECTOR_ENCRYPTION_KEY

5. Runtime

NODE_ENV

LOG_LEVEL

WORKER_CONCURRENCY

6. Integration Backends

EVENT_PUBLISHER

CACHE_STORE

INTERACTION_STORE

SEARCH_INDEX

7. Observability

OTEL_EXPORTER_OTLP_ENDPOINT

OTEL_SERVICE_NAME

OTEL_EXPORTER_OTLP_PROTOCOL

OTEL_TRACES_SAMPLER

OTEL_TRACES_SAMPLER_ARG

8. Kafka Integration (Manual Config)

KAFKA_BROKERS

KAFKA_TOPIC_PREFIX

KAFKA_SASL_USERNAME / KAFKA_SASL_PASSWORD

9. AWS Integration (Manual Config)

AWS_REGION

SNS_TOPIC_ARN

DYNAMODB_TABLE_NAME

10. Search Integration (Manual Config)

OPENSEARCH_URL

OPENSEARCH_INDEX_PREFIX

11. Analytics Integration (Manual Config)

CLICKHOUSE_URL

CLICKHOUSE_DATABASE

12. Example .env Files

Development

Production (Minimal — PostgreSQL Only)

Production (Full Infrastructure via Env Vars)