Skip to main content

​
Overview

For production workloads, Helicone provides a production-ready Helm chart that deploys all services to Kubernetes with:
  • Horizontal auto-scaling
  • High availability
  • Resource management
  • Service discovery
  • Rolling updates
  • Health checks and probes

​
Prerequisites

  • Kubernetes 1.24 or later
  • Helm 3.8 or later
  • kubectl configured to access your cluster
  • 16GB+ memory across nodes
  • 100GB+ storage (persistent volumes)

​
Getting the Helm Chart

The Helm chart is available for enterprise customers. Contact us to get access:

Get Enterprise Access

Email enterprise@helicone.ai to request the Helm chart and production support

​
Quick Start

Once you have access to the Helm chart:
1

Add the Helm repository

helm repo add helicone https://charts.helicone.ai
helm repo update
2

Create a namespace

kubectl create namespace helicone
3

Configure values

Create a values.yaml file with your configuration:
# values.yaml
global:
  domain: helicone.your-domain.com
  
auth:
  secret: "your-secure-random-secret-key"
  
postgresql:
  enabled: true
  auth:
    password: "secure-postgres-password"
  primary:
    persistence:
      size: 100Gi
      
clickhouse:
  enabled: true
  persistence:
    size: 500Gi
    
minio:
  enabled: true
  auth:
    rootUser: admin
    rootPassword: "secure-minio-password"
  persistence:
    size: 1Ti
    
jawn:
  replicaCount: 3
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
      
web:
  replicaCount: 2
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi
4

Install Helicone

helm install helicone helicone/helicone \
  -n helicone \
  -f values.yaml
5

Verify installation

# Check pod status
kubectl get pods -n helicone

# Check services
kubectl get svc -n helicone

# View logs
kubectl logs -n helicone -l app=jawn -f

​
Architecture on Kubernetes

Helicone deploys the following workloads: 
┌─────────────────────────────────────────────────────┐
│                   Ingress / Load Balancer            │
│                 (helicone.your-domain.com)           │
└──────────────┬────────────────────┬─────────────────┘
               │                    │
         ┌─────▼──────┐      ┌─────▼─────┐
         │    Web     │      │   Jawn    │
         │ (Next.js)  │      │  (API)    │
         │ 2 replicas │      │ 3 replicas│
         └─────┬──────┘      └─────┬─────┘
               │                    │
         ┌─────▼────────────────────▼─────┐
         │                                 │
    ┌────▼────┐  ┌──────────┐  ┌─────────▼──┐
    │PostgreSQL│  │ClickHouse│  │   MinIO    │
    │StatefulSet│ │StatefulSet│ │StatefulSet │
    │(Primary +│  │(Cluster) │  │ (Cluster)  │
    │ Replica) │  │          │  │            │
    └──────────┘  └──────────┘  └────────────┘
         │              │              │
    ┌────▼────┐   ┌─────▼────┐  ┌─────▼────┐
    │ PV: 100G│   │ PV: 500G │  │ PV: 1TB  │
    └─────────┘   └──────────┘  └──────────┘

​
Configuration Reference

​
Global Settings

global:
  # Domain for ingress
  domain: helicone.example.com
  
  # Image registry (optional)
  imageRegistry: docker.io
  
  # Storage class for PVCs
  storageClass: "fast-ssd"

​
Authentication

auth:
  # Secret key for session encryption (REQUIRED)
  secret: "change-me-to-random-32-char-string"
  
  # Existing secret (optional)
  existingSecret: "helicone-auth-secret"
  existingSecretKey: "auth-secret"

​
PostgreSQL (Application Database)

postgresql:
  enabled: true  # Set to false to use external database
  
  auth:
    username: postgres
    password: "secure-password"
    database: helicone
  
  primary:
    persistence:
      enabled: true
      size: 100Gi
      storageClass: "fast-ssd"
    
    resources:
      requests:
        cpu: 2000m
        memory: 4Gi
      limits:
        cpu: 4000m
        memory: 8Gi
  
  # External database configuration
  external:
    host: postgres.external.com
    port: 5432
    database: helicone
    username: helicone_user
    password: "password"

​
ClickHouse (Analytics Database)

clickhouse:
  enabled: true  # Set to false to use external ClickHouse
  
  persistence:
    enabled: true
    size: 500Gi
    storageClass: "fast-ssd"
  
  resources:
    requests:
      cpu: 4000m
      memory: 8Gi
    limits:
      cpu: 8000m
      memory: 16Gi
  
  # Replication (for HA)
  replicaCount: 3
  
  # External ClickHouse
  external:
    host: clickhouse.external.com
    port: 8123
    user: default
    password: ""

​
MinIO (Object Storage)

minio:
  enabled: true  # Set to false to use S3/GCS
  
  auth:
    rootUser: admin
    rootPassword: "secure-password"
  
  persistence:
    enabled: true
    size: 1Ti
    storageClass: "standard"
  
  # For HA setup
  mode: distributed
  replicaCount: 4
  
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi

# Or use external S3-compatible storage
s3:
  endpoint: https://s3.amazonaws.com
  region: us-east-1
  bucket: helicone-storage
  accessKeyId: "AKIA..."
  secretAccessKey: "secret..."

​
Jawn (Backend API)

jawn:
  replicaCount: 3
  
  image:
    repository: helicone/jawn
    tag: latest
    pullPolicy: IfNotPresent
  
  resources:
    requests:
      cpu: 1000m
      memory: 2Gi
    limits:
      cpu: 2000m
      memory: 4Gi
  
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70
    targetMemoryUtilizationPercentage: 80
  
  env:
    LOG_LEVEL: info
    NODE_ENV: production

​
Web (Frontend)

web:
  replicaCount: 2
  
  image:
    repository: helicone/web
    tag: latest
  
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: 1000m
      memory: 2Gi
  
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 5

​
Ingress

ingress:
  enabled: true
  className: nginx  # or 'traefik', 'alb', etc.
  
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  
  hosts:
    - host: helicone.example.com
      paths:
        - path: /
          pathType: Prefix
          service: web
        - path: /v1
          pathType: Prefix
          service: jawn
  
  tls:
    - secretName: helicone-tls
      hosts:
        - helicone.example.com

​
Using External Managed Services

For production, we recommend using managed services:

​
AWS Example

# Disable bundled databases
postgresql:
  enabled: false
  external:
    host: helicone.abc123.us-east-1.rds.amazonaws.com
    port: 5432
    database: helicone
    username: helicone
    password: "${POSTGRES_PASSWORD}"  # Use secret

clickhouse:
  enabled: false
  external:
    host: clickhouse.abc123.us-east-1.amazonaws.com
    port: 8443
    secure: true

minio:
  enabled: false

s3:
  endpoint: https://s3.us-east-1.amazonaws.com
  region: us-east-1
  bucket: helicone-prod-storage
  accessKeyId: "${AWS_ACCESS_KEY_ID}"
  secretAccessKey: "${AWS_SECRET_ACCESS_KEY}"

​
Monitoring and Observability

The Helm chart includes Prometheus metrics and health checks: 
monitoring:
  enabled: true
  
  serviceMonitor:
    enabled: true
    namespace: monitoring
  
  grafana:
    enabled: true
    dashboards:
      enabled: true

​
Available Metrics

  • Request latency (p50, p95, p99)
  • Request volume
  • Error rates
  • Database connection pools
  • Cache hit rates

​
Backup and Disaster Recovery

​
PostgreSQL Backups

postgresql:
  backup:
    enabled: true
    schedule: "0 2 * * *"  # Daily at 2 AM
    retention: 30  # Keep 30 days
    destination: s3://helicone-backups/postgres

​
ClickHouse Backups

clickhouse:
  backup:
    enabled: true
    schedule: "0 3 * * *"
    retention: 7
    destination: s3://helicone-backups/clickhouse

​
Scaling

​
Manual Scaling

# Scale Jawn replicas
kubectl scale deployment/helicone-jawn -n helicone --replicas=5

# Scale Web replicas
kubectl scale deployment/helicone-web -n helicone --replicas=3

​
Auto-Scaling

HPA (Horizontal Pod Autoscaler) is configured in values.yaml: 
jawn:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 20
    metrics:
      - type: Resource
        resource:
          name: cpu
          target:
            type: Utilization
            averageUtilization: 70
      - type: Resource
        resource:
          name: memory
          target:
            type: Utilization
            averageUtilization: 80

​
Upgrading

# Update Helm repo
helm repo update

# Check what will change
helm diff upgrade helicone helicone/helicone \
  -n helicone \
  -f values.yaml

# Perform upgrade
helm upgrade helicone helicone/helicone \
  -n helicone \
  -f values.yaml \
  --wait

​
Troubleshooting

Check pod events and logs:
kubectl describe pod -n helicone <pod-name>
kubectl logs -n helicone <pod-name> --previous
Verify database connectivity:
# Test from a debug pod
kubectl run -it --rm debug --image=postgres:17 -n helicone -- \
  psql -h helicone-postgresql -U postgres
Check storage class and PVC status:
kubectl get pvc -n helicone
kubectl describe pvc -n helicone <pvc-name>

​
Production Checklist

1

Security

  • Changed all default passwords
  • Configured TLS/SSL certificates
  • Set up network policies
  • Enabled pod security policies
  • Configured RBAC
2

High Availability

  • Multiple replicas for stateless services
  • Database replication configured
  • Anti-affinity rules set
  • PodDisruptionBudgets configured
3

Monitoring

  • Prometheus metrics enabled
  • Grafana dashboards imported
  • Alerts configured
  • Log aggregation set up
4

Backup

  • Automated backups configured
  • Backup restoration tested
  • Retention policies set
5

Performance

  • Resource limits configured
  • Auto-scaling enabled
  • PersistentVolume performance tested

​
Next Steps

Architecture

Understand the system architecture

Enterprise Support

Get help with your production deployment