Deploy on Kubernetes

Helion can be deployed on Kubernetes using the community-maintained Helm chart. This allows you to run Helion in a scalable, production-ready Kubernetes environment.

The Helm chart is maintained by the community and available on Artifact Hub.

Prerequisites

Kubernetes 1.19+
Helm 3.0+
kubectl configured to access your cluster
At least 2GB RAM per node (4GB+ recommended)
Persistent volume support (if using self-hosted databases)

Quick Start

Add the Helm Repository

Add the Helion Helm repository:

helm repo add helion https://yashGoyal40.github.io/helion
helm repo update

Download Default Values

Download the default values file to customize your configuration:

helm show values Shrotriya-lalit/helionlabs > my-values.yaml

⚠️ IMPORTANT: Before installing, you MUST configure the required values in values.yaml. The chart includes placeholder values (marked with <>) that will cause the installation to fail if not properly configured.

Configure Required Values

Edit my-values.yaml and configure the following required values:

Ingress Configuration:

ingress:
  enabled: true
  type: standard  # or "httpproxy" for Contour
  fqdn: your-domain.com  # Replace with your actual domain
  standard:
    tlsSecretName: helion-tls

Application URLs:

config:
  apiUrl: "https://your-domain.com/api"
  dashboardUrl: "https://your-domain.com"
  googleRedirectUri: "https://your-domain.com/api/oauth/google/callback"

Cookie Secret (generate with openssl rand -base64 32):

secrets:
  cookieSecret: "YOUR_GENERATED_SECRET_HERE"

PostgreSQL Configuration (choose one):

Option A: External PostgreSQL (recommended for production)

postgresql:
  enabled: false
externalPostgresql:
  host: "postgres.example.com"
  port: 5432
  user: "helion"
  password: "your-secure-password"
  database: "helion"
  schema: public

Option B: Self-hosted PostgreSQL

postgresql:
  enabled: true
  user: postgres
  password: "your-secure-password"
  database: postgres
  persistence:
    size: 20Gi

Install Helion

Install Helion with your configured values:

helm install my-helion Shrotriya-lalit/helionlabs \
  --version 0.1.0 \
  --namespace helion \
  --create-namespace \
  -f my-values.yaml

Or override specific values directly:

helm install my-helion Shrotriya-lalit/helionlabs \
  --version 0.1.0 \
  --namespace helion \
  --create-namespace \
  --set ingress.fqdn=your-domain.com \
  --set config.apiUrl=https://your-domain.com/api \
  --set secrets.cookieSecret=$(openssl rand -base64 32)

Verify Installation

Check that all pods are running:

kubectl get pods -n helion

You should see pods for:

API server (op-api)
Dashboard (op-dashboard)
Worker (op-worker)
PostgreSQL (if using self-hosted)
Redis (if using self-hosted)
ClickHouse (if using self-hosted)

Check the status:

kubectl get all -n helion

Access Your Dashboard

Once all pods are running, access Helion at your configured domain. The ingress will route traffic to the dashboard service.

If you need to test locally, you can port-forward:

kubectl port-forward svc/op-dashboard 3000:80 -n helion

Then access Helion at http://localhost:3000.

Configuration

Required Configuration

The following values MUST be configured before installation:

Configuration	Required	Placeholder	Description
`ingress.fqdn`	✅ Yes	`<fqdn>`	Your domain name
`ingress.*.tlsSecretName`	✅ Yes	`<tls_secret_name>`	TLS certificate secret name
`config.apiUrl`	✅ Yes	`<fqdn>`	Full API URL
`config.dashboardUrl`	✅ Yes	`<fqdn>`	Full Dashboard URL
`config.googleRedirectUri`	✅ Yes	`<fqdn>`	OAuth callback URL
`secrets.cookieSecret`	✅ Yes	`CHANGE_ME_...`	Session encryption key
`externalPostgresql.*`	⚠️ If external	`<postgres_*>`	PostgreSQL connection details

Complete Example Configuration

Here's a minimal example configuration file (my-values.yaml) with all required values:

my-values.yaml

# Ingress Configuration
ingress:
  enabled: true
  type: standard  # or "httpproxy" for Contour
  fqdn: analytics.example.com
  standard:
    tlsSecretName: helion-tls

# Application URLs
config:
  apiUrl: "https://analytics.example.com/api"
  dashboardUrl: "https://analytics.example.com"
  googleRedirectUri: "https://analytics.example.com/api/oauth/google/callback"

# Cookie Secret (generate with: openssl rand -base64 32)
secrets:
  cookieSecret: "YOUR_GENERATED_SECRET_HERE"

# PostgreSQL - Using External Database
postgresql:
  enabled: false

externalPostgresql:
  host: "postgres.example.com"
  port: 5432
  user: "helion"
  password: "your-secure-password"
  database: "helion"
  schema: public

Optional Configuration

The Helm chart maps environment variables to Helm values. For a complete reference of all available environment variables and their descriptions, see the Environment Variables documentation.

Email Configuration

Enable email functionality (password resets, invitations, etc.):

secrets:
  resendApiKey: "re_xxxxxxxxxxxxx"  # Your Resend API key
  emailSender: "noreply@your-domain.com"  # Verified sender email

Get your Resend API key from resend.com. Make sure to verify your sender email domain.

AI Features

Enable the in-app AI chat assistant by setting one or both provider API keys:

secrets:
  openaiApiKey: "sk-xxxxxxxxxxxxx"          # For GPT-4.1 / 4.1 mini / 5.4 mini
  anthropicApiKey: "sk-ant-xxxxxxxxxxxxx"   # For Claude Haiku 4.5 / Sonnet 4.6 / Opus 4.6

The chat's model picker only shows models whose provider has a key configured — set either or both. Without any key, the chat drawer still opens but shows a setup hint.

Google OAuth

Enable Google OAuth login:

secrets:
  googleClientId: "xxxxx.apps.googleusercontent.com"
  googleClientSecret: "GOCSPX-xxxxxxxxxxxxx"

Set up Google OAuth in Google Cloud Console. Add authorized redirect URI: https://your-domain.com/api/oauth/google/callback

Redis Configuration

Redis is enabled by default and deployed within Kubernetes. To use an external Redis instance:

redis:
  enabled: false

externalRedis:
  host: "redis.example.com"
  port: 6379

ClickHouse Configuration

ClickHouse is enabled by default and deployed within Kubernetes. To use an external ClickHouse instance:

clickhouse:
  enabled: false

externalClickhouse:
  host: "clickhouse.example.com"
  port: 8123
  database: helion

Application Components

Enable/disable individual components:

api:
  enabled: true
  replicas: 1

dashboard:
  enabled: true
  replicas: 1

worker:
  enabled: true
  replicas: 1

Resource Limits

Adjust resource requests and limits:

api:
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "2Gi"
      cpu: "2000m"

Updating Helion

To upgrade to a newer version:

helm repo update
helm upgrade my-helion Shrotriya-lalit/helionlabs \
  --version <new-version> \
  --namespace helion \
  -f my-values.yaml

Replace <new-version> with the desired version number (e.g., 0.1.1).

Managing Your Deployment

View Logs

View logs from specific deployments:

# API logs
kubectl logs -f deployment/op-api -n helion

# Dashboard logs
kubectl logs -f deployment/op-dashboard -n helion

# Worker logs
kubectl logs -f deployment/op-worker -n helion

Restart Services

Restart a specific deployment:

kubectl rollout restart deployment/op-api -n helion
kubectl rollout restart deployment/op-dashboard -n helion
kubectl rollout restart deployment/op-worker -n helion

Scale Services

Scale services on the fly:

kubectl scale deployment/op-worker --replicas=3 -n helion

Or update your values file and upgrade:

worker:
  replicas: 3

helm upgrade my-helion Shrotriya-lalit/helionlabs -f my-values.yaml -n helion

Check Services

View all services:

kubectl get svc -n helion

Check ConfigMap and Secrets

Verify configuration:

kubectl get configmap helion-config -n helion -o yaml
kubectl get secret helion-secrets -n helion -o yaml

Ingress Configuration

Standard Ingress (NGINX/Traefik)

ingress:
  enabled: true
  type: standard
  fqdn: helion.your-domain.com
  standard:
    tlsSecretName: helion-tls
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/ssl-redirect: "true"

HTTPProxy (Contour)

ingress:
  enabled: true
  type: httpproxy
  fqdn: helion.your-domain.com
  httpproxy:
    tlsSecretName: helion-tls

Troubleshooting

Pods Not Starting

Check pod status:

kubectl describe pod <pod-name> -n helion

Check events:

kubectl get events --sort-by='.lastTimestamp' -n helion

Check logs:
```
kubectl logs <pod-name> -n helion
```

Database Connection Issues

Verify database pods are running (if using self-hosted):
```
kubectl get pods -n helion | grep postgres
```

Check database service:

kubectl get svc -n helion | grep postgres

Test database connection:

kubectl exec -it deployment/op-api -n helion -- env | grep DATABASE_URL

Configuration Issues

If pods are failing due to configuration:

Verify all required values are set:
```
helm get values my-helion -n helion
```

Check for placeholder values:

helm get values my-helion -n helion | grep "<"

Ensure secrets are properly set:

kubectl get secret helion-secrets -n helion -o yaml

Ingress Not Working

Check ingress status:

kubectl get ingress -n helion
kubectl describe ingress -n helion

Verify ingress controller is running:

kubectl get pods -n ingress-nginx  # For NGINX
# or
kubectl get pods -n projectcontour  # For Contour

Check DNS configuration

Backup and Restore

Backup PostgreSQL

If using self-hosted PostgreSQL:

kubectl exec -it <postgresql-pod-name> -n helion -- \
  pg_dump -U postgres helion > backup.sql

Or use a Kubernetes CronJob for automated backups.

Restore PostgreSQL

Restore from backup:

kubectl exec -i <postgresql-pod-name> -n helion -- \
  psql -U postgres helion < backup.sql

Uninstalling

To uninstall Helion:

helm uninstall my-helion --namespace helion

⚠️ Warning: This will delete all resources including persistent volumes. Make sure to backup your data before uninstalling!

To keep persistent volumes:

# Delete the release but keep PVCs
helm uninstall my-helion --namespace helion

# Manually delete PVCs if needed
kubectl delete pvc -l app.kubernetes.io/name=helion -n helion

Next Steps

Configure email settings for password resets and invitations
Set up AI integration for the analytics assistant
Configure SDK to track events from your applications

On this page