Skip to main content

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.

This guide covers deploying KaireonAI using a fully managed cloud stack — no servers to maintain, automatic scaling, and managed databases.

​
Architecture

​
Production Stack

ServiceProviderPurposePricing
App RuntimeAWS App RunnerHosts the Next.js applicationPay per vCPU/memory
DatabaseSupabase (PostgreSQL)Primary data store via Prisma 7Free tier available
CacheUpstash (Redis)Enrichment caching, rate limitingFree tier available
DNSRoute 53Domain management~$0.50/zone/month
CDNCloudFrontMarketing site + static assetsPay per request
Container RegistryAmazon ECRDocker image storagePay per GB

​
Step-by-Step Setup

1

Create a Supabase project

  1. Go to supabase.com and create a new project
  2. Choose a region close to your App Runner deployment
  3. Copy the Connection string (Settings → Database → URI)
  4. The format is: postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
Use the Session mode connection string (port 5432), not the pooler (port 6543), for Prisma migrations. App Runner can use either.
2

Create an Upstash Redis database

  1. Go to upstash.com and create a new Redis database
  2. Choose the same region as your Supabase project
  3. Copy the Redis URL (starts with rediss://)
  4. Upstash provides TLS by default — the rediss:// protocol handles encryption
3

Push Docker image to ECR

# Authenticate with ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

# Build and push
docker build -t kaireon-api .
docker tag kaireon-api:latest <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:latest
docker push <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:latest
4

Create App Runner service

  1. Go to the AWS App Runner console
  2. Choose Container registry → Amazon ECR as the source
  3. Select the kaireon-api repository and latest tag
  4. Configure:
    • CPU: 1 vCPU (or 2 for production)
    • Memory: 2 GB (or 4 for production)
    • Port: 3000
  5. Add environment variables:
DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres
REDIS_URL=rediss://default:[password]@[host].upstash.io:6379
NEXTAUTH_SECRET=[generate-a-secure-random-string]
NEXTAUTH_URL=https://your-domain.com
NODE_ENV=production
5

Initialize the database

Run migrations against your Supabase database from your local machine:
DATABASE_URL="postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres" \
  npx prisma db push
Then seed the admin user:
DATABASE_URL="postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres" \
  npx tsx prisma/seed.ts
6

Configure custom domain (optional)

  1. In App Runner, go to Custom domains and add your domain
  2. Create a CNAME record in Route 53 pointing to the App Runner URL
  3. App Runner automatically provisions and renews TLS certificates

​
Updating

To deploy a new version: 
# Build with git SHA tag
SHA=$(git rev-parse --short HEAD)
docker build -t kaireon-api .
docker tag kaireon-api:latest <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:$SHA
docker tag kaireon-api:latest <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:latest
docker push <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:$SHA
docker push <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/kaireon-api:latest
App Runner automatically redeploys when you push a new image (if auto-deployment is enabled), or you can trigger a manual deployment from the console.

​
Monitoring

  • App Runner logs — Available in the App Runner console or CloudWatch
  • Supabase dashboard — Monitor database connections, query performance, and storage
  • Upstash dashboard — Monitor Redis commands, memory usage, and latency

​
Required Environment Variables (Production)

In addition to the core variables shown above, production deployments on App Runner should include these security-related variables. The platform validates them at startup and will refuse to start if they are missing: 
JWT_SIGNING_SECRET=[generate-a-secure-random-string-min-32-chars]
CONNECTOR_ENCRYPTION_KEY=[32-byte-hex-key-for-credential-encryption]
WEBHOOK_SIGNING_SECRET=[random-string-for-signing-outbound-webhooks]
API_KEY_PEPPER=[random-string-for-api-key-hashing]
CORS_ALLOWED_ORIGINS=https://your-domain.com
See the full environment variable reference for all available configuration.

​
Troubleshooting

ECR login tokens expire after 12 hours. Re-authenticate before pushing:
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin <YOUR_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com
If using CI/CD, ensure your pipeline refreshes the token on each run.
App Runner expects the application to respond on the configured port within 120 seconds. Common causes:
  • Missing environment variables — The platform validates DATABASE_URL and production secrets at startup. Check the App Runner logs in CloudWatch for [env-validation] Missing required environment variables.
  • Insufficient memory — The Next.js build requires at least 2 GB. For production, allocate 4 GB.
  • Database unreachable — Ensure the Supabase connection string uses the direct connection (port 5432), not the pooler, and that the App Runner VPC can reach the database.
Supabase databases may require SSL. Ensure your DATABASE_URL includes ?sslmode=require if connecting from App Runner:
DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres?sslmode=require
Also verify the connection string uses the correct port (5432 for session mode, 6543 for transaction pooler).
App Runner deployments can take 5-10 minutes. If stuck beyond 15 minutes, check CloudWatch logs for the service. You may need to cancel the deployment and redeploy. Common causes include oversized Docker images (keep under 1 GB) and slow health checks.

​
Next Steps

Kubernetes Deployment

Self-host on any Kubernetes cluster with Helm.

Operations

Set up monitoring, metrics, and alerting.