Skip to main content

Deployment

Development (Docker Compose)​

The included docker-compose.yml starts PostgreSQL and Redis:

docker compose up -d

Services:

  • agentcore_postgres — PostgreSQL 16 + pgvector (port 5432)
  • agentcore_redis — Redis 7 Alpine (port 6379)

Both services have health checks and persistent volumes.

Dev Container​

The Dockerfile is for development only:

docker build -t agentcore .
docker run -p 3000:3000 --env-file .env agentcore

This runs npm run dev with hot reload.

Production​

Production auto-deploy is configured in .github/workflows/deploy.yml. On every push to main, GitHub Actions SSHes into AX43, pulls the repository, applies Prisma migrations, builds, restarts PM2 app kalheon-api, and smoke-tests the public health and OpenAPI endpoints.

See the Kalheon deployment runbook at drop/kalheon/DEPLOYMENT.md.

Prerequisites​

  • Node.js 22+
  • PostgreSQL 16 with pgvector extension
  • Redis 7+
  • OpenAI API key

Build​

npm ci
npx prisma generate
npm run build

Database​

DATABASE_URL=<production-url> npx prisma migrate deploy

Run​

NODE_ENV=production npm start

Or with PM2:

pm2 start dist/server.js --name agentcore

Production Checklist​

  • Set NODE_ENV=production
  • Generate strong JWT_SECRET (32+ random chars)
  • Generate PII_ENCRYPTION_KEY as a base64-encoded 32-byte key and store it separately from JWT_SECRET
  • Use managed PostgreSQL with pgvector (e.g., Supabase, RDS)
  • Use managed Redis (e.g., ElastiCache, Upstash)
  • Set ALLOWED_ORIGINS to production frontend domain
  • Configure WhatsApp Cloud API credentials
  • Configure Telegram bot token
  • Set up reverse proxy (nginx) with SSL
  • Enable Langfuse tracing for monitoring
  • Run prisma migrate deploy
  • Set up process manager (PM2, systemd)
  • Configure log rotation

Reverse Proxy (nginx)​

server {
    listen 443 ssl;
    server_name api.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Environment Variables​

See the README environment table for the full list. In production:

  • set ALLOWED_ORIGINS to exact frontend origins only; wildcard CORS is rejected;
  • set JWT_EXPIRES_IN once and rely on it as the JWT lifetime source;
  • set PII_ENCRYPTION_KEY to a stable base64-encoded 32-byte key before processing live conversations;
  • keep Redis available because BullMQ and the production rate-limit store depend on it;
  • configure WhatsApp Cloud API and Telegram credentials only for channels you intend to run.

The global API rate limit is 100 requests per minute per authenticated user or client IP. /api/v1/health and loopback clients are allowlisted.