---
title: Install on Kubernetes
description: Deploy Cuitty to a Kubernetes cluster using the Helm chart, suitable for production workloads.
section: Install
order: 2
updatedAt: 2026-04-27
slug: install/kubernetes
---
# Install on Kubernetes

The official Helm chart deploys Cuitty as a stateful application backed by an external Postgres and an in-cluster SpiceDB.

## Prerequisites

- Kubernetes 1.27 or newer
- Helm 3.13 or newer
- An external Postgres 15+ (RDS, Cloud SQL, or self-managed)
- A persistent volume class for libSQL data

## Install the chart

```bash
helm repo add cuitty https://charts.cuitty.com
helm repo update

helm install cuitty cuitty/cuitty \
  --namespace cuitty --create-namespace \
  --set postgres.url=postgres://cuitty@db.example.com/cuitty \
  --set auth.secretRef=cuitty-secrets
```

The chart provisions:

- `Deployment` for the portal (3 replicas by default)
- `StatefulSet` for SpiceDB
- `PersistentVolumeClaim` for libSQL data
- `Service` and optional `Ingress`
- `NetworkPolicy` restricting egress to allowlisted destinations

## Values

| Key                         | Default       | Notes                                                         |
| --------------------------- | ------------- | ------------------------------------------------------------- |
| `replicaCount`              | `3`           | Portal HTTP replicas.                                         |
| `postgres.url`              | required      | Postgres DSN. Use a `Secret` and `valueFrom` in production.   |
| `spicedb.replicaCount`      | `2`           | SpiceDB replicas. Increase for higher RBAC throughput.        |
| `libsql.storage.size`       | `20Gi`        | Per-module event storage.                                     |
| `ingress.enabled`           | `false`       | Enable to expose `/` via your ingress controller.             |
| `image.tag`                 | chart version | Pin to a specific portal tag in production.                   |

## Upgrades

Helm runs database migrations as a `Job` before swapping the new pod template. A failed migration aborts the upgrade with the previous version still serving.

```bash
helm upgrade cuitty cuitty/cuitty --version 0.4.0
```