Install with Helm

This page installs the self-hosted edition into your own cluster. If you would rather not operate it, the managed service runs the same application at r5d.chat. The chart and both container images are public, so no registry credentials and no account are required. The chart is published two ways on every release; both serve the identical package.

Helm repository
OCI registry

A classic HTTP Helm repository at charts.r5d.dev. It supports helm search and version discovery.

helm repo add r5d-chat https://charts.r5d.dev
helm repo update
helm search repo r5d-chat --versions

The same chart as an OCI artifact in GHCR. No repository to add, but you must know the version you want.

helm show chart oci://ghcr.io/ricsam/charts/r5d-chat --version 0.1.0

Install

Create the application Secret

Production installations should use an existing Secret rather than putting credentials in a values file. It must contain:

Key	Required	Purpose
`DATABASE_URL`	Yes	PostgreSQL connection string
`BETTER_AUTH_SECRET`	Yes	Session signing key, 32+ characters
`SETTINGS_ENCRYPTION_KEY`	Yes	Encrypts provider credentials, 32+ characters
`SETUP_CLAIM_TOKEN`	Recommended	Gates first-administrator setup
`POSTGRES_PASSWORD`	With bundled DB	Password for the bundled StatefulSet
`AWR_BASE_URL`	Optional	Enables web research tools
`AWR_API_KEY`	Optional	Enables web research tools

See the Quickstart for a generation script.

Write your values file

publicUrl: https://chat.example.com
existingSecret: r5d-chat-secrets

ingress:
  enabled: true
  className: traefik
  host: chat.example.com

postgresql:
  storageClass: rook-ceph-block

workspace:
  storageClass: rook-ceph-block
  storageSize: 10Gi

To publish through a Cloudflare Tunnel instead of an inbound Ingress, create the connector token Secret and enable cloudflared. Configure the tunnel’s public hostname in Cloudflare to point at the control-plane Service, http://r5d-chat-r5d-chat.r5d-chat.svc.cluster.local:80.

cloudflared:
  enabled: true
  tokenSecret:
    name: cloudflared-tunnel
    key: token

Every available key is documented in Chart values.

Validate the exact rendered output

Always render and server-dry-run the values you are about to apply.

helm template r5d-chat r5d-chat/r5d-chat \
  --namespace r5d-chat -f values.yaml > /tmp/r5d-chat.yaml
kubectl apply --dry-run=server -f /tmp/r5d-chat.yaml

Install

helm install r5d-chat r5d-chat/r5d-chat \
  --namespace r5d-chat --create-namespace \
  -f values.yaml --wait --timeout 10m

helm install r5d-chat oci://ghcr.io/ricsam/charts/r5d-chat \
  --version 0.1.0 \
  --namespace r5d-chat --create-namespace \
  -f values.yaml --wait --timeout 10m

Verify

kubectl -n r5d-chat rollout status deployment/r5d-chat-r5d-chat
kubectl -n r5d-chat get pods,pvc,ingress
curl -fsS https://chat.example.com/api/health

Image versions

Chart versions and image versions are released together. When image.tag and workspaceImage.tag are empty, the chart uses its own appVersion, so installing chart 0.3.0 runs the images published for 0.3.0. Override the tags only when you deliberately want a different build:

helm upgrade --install r5d-chat r5d-chat/r5d-chat \
  --namespace r5d-chat -f values.yaml \
  --set-string image.tag=deploy-20250219-abc1234 \
  --set-string workspaceImage.tag=deploy-20250219-abc1234

Publishing pipeline

How images and chart versions are built and published.

Private registries

The published images are public, so a pull secret is not required for a normal installation. This section applies only when you mirror the images into a private registry of your own. Create a pull secret and reference it in two places: the control-plane pods use imagePullSecrets, and dynamically created workspace pods use workspace.imagePullSecret.

kubectl -n r5d-chat create secret docker-registry ghcr-pull \
  --docker-server=ghcr.io \
  --docker-username="<github-username>" \
  --docker-password="<token-with-read:packages>"

imagePullSecrets:
  - name: ghcr-pull
workspace:
  imagePullSecret: ghcr-pull

Setting only imagePullSecrets is a common mistake. The control plane will start correctly while every user workspace fails with ImagePullBackOff, because workspace pods are created by the controller at runtime and are not part of the chart’s rendered output.

External PostgreSQL

The bundled database is convenient for evaluation. For production, run PostgreSQL 17 separately:

postgresql:
  enabled: false

Put the external connection string in the DATABASE_URL key of your Secret and make sure network policy allows the control plane to reach it.

What the chart creates

Resource	Notes
Deployment	Control plane, `Recreate` strategy, migrations in an init container
Service	ClusterIP on port 80 targeting container port 3000
Ingress	Only when `ingress.enabled` is true
Secret	Only when `existingSecret` is empty
ServiceAccount, Role, RoleBinding	Namespace-scoped permissions to reconcile workspaces
StatefulSet + headless Service	Only when `postgresql.enabled` is true
NetworkPolicy	Two policies, for the control plane and for workspaces

The control plane uses Recreate rather than a rolling update to avoid surge pods, which keeps it within tight namespace pod quotas. Expect a brief interruption during upgrades.

Uninstall

helm uninstall removes chart-managed compute and routing. It is not a tenant data purge.

kubectl -n r5d-chat get pvc
helm uninstall r5d-chat --namespace r5d-chat
kubectl -n r5d-chat get all,pvc,secret

Workspace PVCs carry keep semantics and survive. Delete them only after confirming your backup and retention decision, as covered in Backup and restore.

Get started

Install

Configure

Operate

Reference

Install with Helm

Install

Image versions

Publishing pipeline

Private registries

External PostgreSQL

What the chart creates

Uninstall

​Install

​Image versions

Publishing pipeline

​Private registries

​External PostgreSQL

​What the chart creates

​Uninstall

Install

Image versions

Private registries

External PostgreSQL

What the chart creates

Uninstall