Installation Guide

​

1. Prerequisites

​

Required Tools

​

Additional Tools by Mode

​

Cluster Requirements

• Dev/Demo: Any Kubernetes cluster (Docker Desktop, kind, minikube, or a remote cluster). Minimum 2 CPU / 4 GB RAM available.
• App-Only: An existing Kubernetes cluster with access to your managed database and cache.
• Full Stack: An AWS account with permissions to create VPC, EKS, RDS, ElastiCache, S3, IAM, and Route 53 resources.

​

Verify Prerequisites

make preflight

​

2. Quick Start (Dev/Demo)

# Clone the repository
git clone https://github.com/OWNER/kaireonai.git
cd kaireonai

# Install in dev mode
make install-dev

1. Creates the kaireon namespace.
2. Deploys an in-cluster PostgreSQL 16 StatefulSet (10 Gi volume).
3. Deploys the KaireonAI API (1 replica) and Worker (1 replica).
4. Runs database schema sync automatically.

Note: Redis, Kafka, OpenSearch, and other infrastructure are not deployed by default. The platform runs entirely on PostgreSQL. To add caching, event streaming, or search indexing, configure them from Settings > Integrations after installation.

​

Access the Application

kubectl port-forward -n kaireon svc/kaireon-api 3000:3000

​

Load Demo Data (Optional)

make seed

​

Override the Namespace

make install-dev NAMESPACE=kaireon-demo

​

3. App-Only Install

​

Step 1 — Create a Configuration File

# kaireon-config.yaml -- App-Only example

database:
  mode: external
  external:
    host: my-rds-instance.abc123.us-east-1.rds.amazonaws.com
    port: 5432
    name: kaireon
    username: kaireon_app
    password: ""                # Leave empty if using existingSecret
    sslMode: require
    existingSecret: kaireon-db   # K8s secret containing the password
    secretKey: password

# Redis is optional — configure via Settings > Integrations UI if needed.
# Uncomment below to provide Redis at install time:
# redis:
#   mode: external
#   external:
#     host: my-redis.abc123.0001.use1.cache.amazonaws.com
#     port: 6379
#     tls: true
#     password: ""
#     existingSecret: kaireon-redis
#     secretKey: password

secrets:
  provider: kubernetes
  NEXTAUTH_SECRET: ""           # Will be auto-generated if empty
  JWT_SIGNING_SECRET: ""
  CONNECTOR_ENCRYPTION_KEY: ""

ingress:
  enabled: true
  className: nginx
  host: app.example.com
  tls:
    enabled: true
    secretName: kaireon-tls
    clusterIssuer: letsencrypt-prod

api:
  replicas: 3
  env:
    NEXTAUTH_URL: "https://app.example.com"

​

Step 2 — Create Kubernetes Secrets (If Using existingSecret)

kubectl create namespace kaireon

kubectl create secret generic kaireon-db \
  -n kaireon \
  --from-literal=password='YOUR_DB_PASSWORD'

# Only needed if you configured Redis in your config file:
# kubectl create secret generic kaireon-redis \
#   -n kaireon \
#   --from-literal=password='YOUR_REDIS_PASSWORD'

​

Step 3 — Install

make install-app CONFIG=kaireon-config.yaml

​

4. Full Stack Install

​

Step 1 — Configure AWS Credentials

aws configure
# or export AWS_PROFILE=your-profile

​

Step 2 — Set Terraform Variables

cd terraform/environments/production

# terraform.tfvars
aws_region        = "us-east-1"
environment       = "production"
project_name      = "kaireon"
domain            = "app.kaireon.com"      # Leave empty to skip DNS/TLS
rds_multi_az      = true
eks_node_max_size = 6
cloudwatch_enabled = true
cloudwatch_email  = "ops@example.com"

​

Step 3 — Initialize and Apply Terraform

terraform init
terraform plan -out=tfplan
terraform apply tfplan

• A VPC with public and private subnets across availability zones.
• An EKS cluster with a managed node group (t3.large, min 2 / max 6 nodes).
• An RDS PostgreSQL instance in private subnets.
• An ElastiCache Redis cluster in private subnets.
• An S3 bucket for backups.
• IAM roles with IRSA for pod-level AWS access.
• Route 53 records and an ACM certificate (if domain is set).
• CloudWatch alarms and dashboards (if enabled).

​

Step 4 — Configure kubectl

aws eks update-kubeconfig \
  --region us-east-1 \
  --name $(terraform output -raw cluster_name)

​

Step 5 — Install the Application

cd /path/to/kaireonai
make install

​

5. Post-Install Verification

​

Check Deployment Status

make status

=== Pods ===
NAME                           READY   STATUS    RESTARTS   AGE
kaireon-api-7b8c9d6e5f-abc12   1/1     Running   0          2m
kaireon-api-7b8c9d6e5f-def34   1/1     Running   0          2m
kaireon-api-7b8c9d6e5f-ghi56   1/1     Running   0          2m
kaireon-worker-4a5b6c7d-jkl78  1/1     Running   0          2m
kaireon-pgbouncer-8e9f0a1b-x9  1/1     Running   0          2m
kaireon-prometheus-0            1/1     Running   0          2m
kaireon-grafana-5c6d7e8f-mn01  1/1     Running   0          2m

=== Services ===
NAME               TYPE        CLUSTER-IP      PORT(S)
kaireon-api         ClusterIP   10.100.45.12    3000/TCP
kaireon-pgbouncer   ClusterIP   10.100.45.13    5432/TCP

=== Health Check ===
{"status":"healthy","version":"1.0.0"}

​

Health Check Endpoints

​

Access Grafana

# Port-forward Grafana
kubectl port-forward -n kaireon svc/kaireon-grafana 3001:3000

# Open http://localhost:3001
# Default credentials: admin / (value of monitoring.grafana.adminPassword or auto-generated)

​

Access Prometheus

kubectl port-forward -n kaireon svc/kaireon-prometheus 9090:9090

​

Tail Logs

make logs          # API logs
make logs-worker   # Worker logs

​

6. Configuration Reference

​

Global

​

API

​

Worker

​

Config

​

Database

​

Redis

​

Secrets

​

Ingress

​

PgBouncer

​

Observability

​

Monitoring (In-Cluster)

​

7. Upgrading

​

Rolling Upgrade

# Pull the latest chart / image tags
git pull origin main

# Upgrade with existing values
make upgrade

​

Upgrade with New Configuration

helm upgrade kaireon ./helm/kaireon \
  -n kaireon \
  -f kaireon-config.yaml

​

Database Schema Sync

make migrate

Note: prisma db push compares the current schema.prisma against the live database and applies changes directly. There are no migration files to track.

​

Version Pinning

api:
  image:
    tag: "1.2.3"
worker:
  image:
    tag: "1.2.3"

​

8. Uninstalling

​

Remove the Application (Keep Infrastructure)

make uninstall

​

Remove Application and Namespace

make destroy

​

Destroy AWS Infrastructure (Full Stack Only)

cd terraform/environments/production
terraform destroy

​

Create a Backup Before Uninstalling

make backup
make uninstall

make restore FILE=path/to/backup.sql.gz

​

9. Troubleshooting FAQ

​

Pods stuck in Pending state

1. Insufficient cluster resources. Check node capacity:
   Copy

   Ask AI

   kubectl describe nodes | grep -A 5 "Allocated resources"
   
   Add more nodes or reduce resource requests in your config.
2. PVC not binding (dev mode). The cluster may lack a default StorageClass:
   Copy

   Ask AI

   kubectl get storageclass
   
   If empty, install a provisioner (e.g., hostpath-provisioner for local clusters) or set one as default:
   Copy

   Ask AI

   kubectl patch storageclass standard -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
   
3. Node selector or taint mismatch. Verify there are no taints preventing scheduling:
   Copy

   Ask AI

   kubectl describe pod <pod-name> -n kaireon | grep -A 10 Events
   

​

Database connection refused

1. Internal mode: Confirm the PostgreSQL pod is running:
   Copy

   Ask AI

   kubectl get pods -n kaireon -l app=kaireon-postgres
   
   Check its logs:
   Copy

   Ask AI

   kubectl logs -n kaireon -l app=kaireon-postgres
   
2. External mode: Verify the host is reachable from inside the cluster:
   Copy

   Ask AI

   kubectl run dbtest --rm -it --image=postgres:16-alpine -n kaireon -- \
     pg_isready -h <DB_HOST> -p 5432
   
3. Security groups (AWS). Ensure the RDS security group allows inbound on port 5432 from the EKS node security group. In full-stack mode, Terraform configures this automatically.
4. PgBouncer misconfiguration. If PgBouncer is enabled, verify it can reach the database:
   Copy

   Ask AI

   kubectl logs -n kaireon -l app=kaireon-pgbouncer
   

​

Redis connection errors

1. Internal mode: Confirm the Redis pod is running:
   Copy

   Ask AI

   kubectl get pods -n kaireon -l app=kaireon-redis
   
2. External mode: Test connectivity:
   Copy

   Ask AI

   kubectl run redistest --rm -it --image=redis:7-alpine -n kaireon -- \
     redis-cli -h <REDIS_HOST> -p 6379 --tls PING
   
3. TLS mismatch. If your external Redis does not use TLS, set redis.external.tls: false.
4. Authentication. Ensure the password in your K8s secret matches the Redis AUTH password:
   Copy

   Ask AI

   kubectl get secret kaireon-redis -n kaireon -o jsonpath='{.data.password}' | base64 -d
   

​

Ingress not working / 404 errors

1. Ingress controller not installed. Verify an ingress controller is running:
   Copy

   Ask AI

   kubectl get pods -n ingress-nginx
   
   If missing, install one:
   Copy

   Ask AI

   helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
   helm install ingress-nginx ingress-nginx/ingress-nginx -n ingress-nginx --create-namespace
   
2. Ingress class mismatch. Ensure ingress.className matches your controller:
   Copy

   Ask AI

   kubectl get ingressclass
   
3. DNS not pointing to the load balancer. Get the external IP:
   Copy

   Ask AI

   kubectl get svc -n ingress-nginx
   
   Create a DNS A/CNAME record pointing your domain to that address.
4. TLS certificate not ready. Check cert-manager:
   Copy

   Ask AI

   kubectl get certificate -n kaireon
   kubectl describe certificate kaireon-tls -n kaireon
   

​

Helm install fails with “namespace not found”

kubectl create namespace kaireon

​

Migrations fail during install

1. Run migrations manually:
   Copy

   Ask AI

   make migrate
   
2. Check migration logs:
   Copy

   Ask AI

   kubectl logs -n kaireon -l job-name=kaireon-migrate
   
3. Verify database connectivity and permissions. The migration user needs CREATE TABLE, ALTER TABLE, and CREATE INDEX privileges.

​

OOMKilled pods

api:
  resources:
    limits:
      memory: "4Gi"

worker:
  resources:
    limits:
      memory: "8Gi"

make upgrade

​

AWS Secrets Manager errors (Full Stack mode)

1. Verify the IRSA role ARN is correct in your config:
   Copy

   Ask AI

   terraform output helm_values
   
2. Confirm the service account is annotated:
   Copy

   Ask AI

   kubectl get sa -n kaireon kaireon-api -o yaml | grep eks.amazonaws.com
   
3. Check the IAM trust policy allows the OIDC provider for your cluster.

​

How to open a shell in the API pod

make shell

​

How to view all available Make targets

make help