# How to Deploy Kaneo on Kubernetes Using Helm Charts: Complete Production Guide

> Deploy Kaneo on Kubernetes with official Helm charts. Install with embedded PostgreSQL or customize for external databases, ingress, and autoscaling.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-06

---

**Deploy Kaneo on Kubernetes using its official Helm chart by installing the `kaneo` release with embedded PostgreSQL, or customize [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) for external databases, ingress, and autoscaling.**

Kaneo provides a production-ready Helm chart in the `usekaneo/kaneo` repository that automates the entire platform deployment. The chart bundles the API and web interface into a single container, optionally provisions PostgreSQL, and supports NGINX Ingress or Kubernetes Gateway API for external access.

## Understanding the Kaneo Helm Chart Structure

The chart follows standard Helm conventions with clear separation of concerns. Located at `charts/kaneo/` in the repository, it organizes all Kubernetes resources into reusable templates.

### Core Components

| Component | Template File | Purpose |
|-----------|-------------|---------|
| **Chart metadata** | [`Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/Chart.yaml) | Defines chart version 2.13.0 and dependencies |
| **Default configuration** | [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) | Supplies replicas, image tags, environment variables, and feature flags |
| **Application deployment** | [`templates/deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/deployment.yaml) | Runs the combined Kaneo container with required environment variables |
| **Database** | [`templates/postgresql-deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/postgresql-deployment.yaml) | Optional embedded PostgreSQL instance |
| **Networking** | [`templates/services.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/services.yaml) | Exposes Kaneo on port 5173 via ClusterIP |
| **External access** | [`templates/ingress.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/ingress.yaml) / [`templates/httproute.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/httproute.yaml) | Optional NGINX Ingress or Gateway API HTTPRoute |
| **Persistence** | [`templates/pvc.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/pvc.yaml) | Persistent storage for PostgreSQL data |
| **Scaling** | [`templates/hpa.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/hpa.yaml) | Horizontal Pod Autoscaler based on CPU metrics |
| **Security** | [`templates/serviceaccount.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/serviceaccount.yaml) | Dedicated ServiceAccount for the Deployment |

All templates reference values from [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml), enabling complete configuration without editing template files directly.

## Prerequisites

Before deploying, ensure your cluster meets these requirements:

- **Kubernetes version**: 1.23.0 or later (specified in [`Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/Chart.yaml) as `kubeVersion: ">=1.23.0-0"`)
- **Helm 3.x** installed locally
- **kubectl** configured for your target cluster
- **Ingress controller** (optional) for external access—NGINX or any Kubernetes Gateway API implementation

## Installing Kaneo with Helm

### Add the Kaneo Helm Repository

```bash
helm repo add kaneo https://usekaneo.github.io/kaneo
helm repo update

```

Skip this step if installing from a local chart copy.

### Basic Installation with Embedded PostgreSQL

The fastest path to a running instance uses all defaults:

```bash
helm install kaneo-instance kaneo/kaneo \
  --namespace kaneo --create-namespace

```

This creates:
- A single-replica Kaneo Deployment with the combined API+web container
- An embedded PostgreSQL Deployment with persistent storage
- A ClusterIP Service exposing port 5173

## Customizing Deployment with values.yaml

For production deployments, override defaults through a custom values file. The [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) in [`charts/kaneo/values.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/values.yaml) exposes all tunable parameters.

### Essential Production Configuration

Create [`production-values.yaml`](https://github.com/usekaneo/kaneo/blob/main/production-values.yaml):

```yaml
replicaCount: 2

kaneo:
  env:
    clientUrl: "https://kaneo.example.com"
    corsOrigins: "https://kaneo.example.com,https://app.example.com"
    authSecret: "your-minimum-32-character-secret-key-here"
    disableRegistration: false
  image:
    repository: usekaneo/kaneo
    tag: "2.13.0"
    pullPolicy: IfNotPresent
  resources:
    limits:
      memory: "512Mi"
      cpu: "500m"
    requests:
      memory: "256Mi"
      cpu: "250m"

postgresql:
  enabled: true
  persistence:
    enabled: true
    size: "20Gi"
    storageClass: "standard"

ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  hosts:
    - host: kaneo.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: kaneo-tls
      hosts:
        - kaneo.example.com

```

Deploy with your custom values:

```bash
helm install kaneo-instance kaneo/kaneo \
  --namespace kaneo --create-namespace \
  -f production-values.yaml

```

### Critical Environment Variables

The [`templates/deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/deployment.yaml) injects these required variables:

| Variable | Source in values.yaml | Purpose |
|----------|----------------------|---------|
| `KANEO_CLIENT_URL` | `kaneo.env.clientUrl` | Public URL for email links and redirects |
| `CORS_ORIGINS` | `kaneo.env.corsOrigins` | Allowed origins for cross-origin requests |
| `AUTH_SECRET` | `kaneo.env.authSecret` | JWT signing key (minimum 32 characters) |
| `DATABASE_URL` | Auto-generated or external | PostgreSQL connection string |

## Connecting to External PostgreSQL

For production databases managed outside the cluster, disable the embedded PostgreSQL and provide connection details:

```yaml
postgresql:
  enabled: false

kaneo:
  env:
    database:
      external:
        enabled: true
        host: "postgres.internal.example.com"
        port: 5432
        database: "kaneo_production"
        username: "kaneo_app"
        password: "secure-password-from-secret"

```

The [`templates/deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/deployment.yaml) constructs `DATABASE_URL` from these values when `postgresql.enabled` is `false`.

## Enabling Horizontal Pod Autoscaling

Scale Kaneo based on CPU utilization by enabling the HPA in [`templates/hpa.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/hpa.yaml):

```yaml
autoscaling:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

```

The HPA automatically adjusts replica count between 2 and 10 pods based on real-time metrics.

## Exposing Kaneo with Ingress or Gateway API

The chart supports two patterns for external traffic.

### NGINX Ingress (Traditional)

Enable in [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml):

```yaml
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: kaneo.example.com
      paths:
        - path: /
          pathType: Prefix
          service: kaneo
          port: 5173

```

The [`templates/ingress.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/ingress.yaml) generates the appropriate Ingress resource.

### Kubernetes Gateway API (Modern)

For Gateway API implementations (Envoy Gateway, NGINX Gateway Fabric, Istio):

```yaml
gateway:
  enabled: true
  gatewayName: external-gateway
  hostname: kaneo.example.com
  listenerName: https

```

The [`templates/httproute.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/httproute.yaml) creates an HTTPRoute resource.

## Upgrading and Maintaining Your Deployment

### Upgrade to New Chart Version

```bash
helm upgrade kaneo-instance kaneo/kaneo \
  --namespace kaneo \
  -f production-values.yaml

```

### Rollback on Failure

```bash
helm rollback kaneo-instance 1 --namespace kaneo

```

### Uninstall Completely

```bash
helm uninstall kaneo-instance --namespace kaneo
kubectl delete namespace kaneo

```

## Key Source Files Reference

| File | Purpose |
|------|---------|
| [[`charts/kaneo/Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/Chart.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/Chart.yaml) | Chart metadata and versioning |
| [[`charts/kaneo/values.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/values.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/values.yaml) | Complete default configuration |
| [[`charts/kaneo/templates/deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/deployment.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/deployment.yaml) | Main application Deployment |
| [[`charts/kaneo/templates/postgresql-deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/postgresql-deployment.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/postgresql-deployment.yaml) | Optional database Deployment |
| [[`charts/kaneo/templates/ingress.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/ingress.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/ingress.yaml) | NGINX Ingress resource |
| [[`charts/kaneo/templates/httproute.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/httproute.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/httproute.yaml) | Gateway API HTTPRoute |
| [[`charts/kaneo/templates/hpa.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/hpa.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/hpa.yaml) | Horizontal Pod Autoscaler |
| [[`charts/kaneo/templates/validations.yaml`](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/validations.yaml)](https://github.com/usekaneo/kaneo/blob/main/charts/kaneo/templates/validations.yaml) | Input validation helpers |

## Summary

- The **Kaneo Helm chart** packages the complete platform into a single installable unit with configurable PostgreSQL, networking, and scaling options.
- **Default installation** requires only `helm install` with embedded database for quick evaluation.
- **Production deployments** should customize [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml) to set `authSecret`, `clientUrl`, external database connections, and ingress configuration.
- **Autoscaling** enables via `autoscaling.enabled` with CPU/memory thresholds in [`templates/hpa.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/hpa.yaml).
- **Gateway API support** provides a modern alternative to traditional Ingress through [`templates/httproute.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/httproute.yaml).

## Frequently Asked Questions

### Does the Kaneo Helm chart support high availability?

Yes. Set `replicaCount` above 1 and enable `autoscaling` for native HA. For database HA, disable embedded PostgreSQL (`postgresql.enabled: false`) and connect to an externally managed PostgreSQL cluster with replication.

### What Kubernetes versions are compatible with the Kaneo Helm chart?

The chart requires Kubernetes 1.23.0 or later, as specified in [`Chart.yaml`](https://github.com/usekaneo/kaneo/blob/main/Chart.yaml) with `kubeVersion: ">=1.23.0-0"`. This ensures support for stable Gateway API and security features used in the templates.

### How do I use my own TLS certificates instead of cert-manager?

Omit the `cert-manager.io/cluster-issuer` annotation from `ingress.annotations` and manually create a TLS secret in the Kaneo namespace. Reference it in `ingress.tls[0].secretName` within your [`values.yaml`](https://github.com/usekaneo/kaneo/blob/main/values.yaml).

### Can I run Kaneo without the embedded PostgreSQL for local development?

Yes. Set `postgresql.enabled: false` and provide `kaneo.env.database.external` credentials, or use a local PostgreSQL instance accessible from your cluster. The [`templates/deployment.yaml`](https://github.com/usekaneo/kaneo/blob/main/templates/deployment.yaml) constructs the connection URL from your external configuration.