Self-hosting with Helm - Sure Docs (draft)

This guide shows you how to deploy Sure on Kubernetes using the official Helm chart. The chart supports web (Rails) and worker (Sidekiq) workloads, optional in-cluster PostgreSQL and Redis, and production-grade features like pre-upgrade migrations, pod security contexts, and horizontal pod autoscaling.

Prerequisites

Kubernetes >= 1.25
Helm >= 3.10
Basic familiarity with Kubernetes and Helm

Features

Web (Rails) deployment with service and optional ingress
Worker (Sidekiq) deployment
Optional database migrations via Helm hook job or initContainer
Optional subcharts for PostgreSQL (CloudNativePG) and Redis (OT-CONTAINER-KIT redis-operator)
Security best practices: runAsNonRoot, readOnlyRootFilesystem, no hardcoded secrets
Scalability: replicas, resources, topology spread constraints, optional HPAs
Optional CronJobs for custom tasks

Installation

Add Helm repositories

Add the Sure Helm repository:

helm repo add sure https://we-promise.github.io/sure
helm repo update

If you plan to use the bundled PostgreSQL or Redis subcharts, add their repositories as well:

helm repo add cloudnative-pg https://cloudnative-pg.github.io/charts
helm repo add ot-helm https://ot-container-kit.github.io/helm-charts
helm repo update

Quickstart (turnkey self-hosting)

This installs CloudNativePG operator with a Postgres cluster and Redis managed by the OT redis-operator.

For production stability, use immutable image tags (for example, image.tag=v1.2.3) instead of latest.

Do not pass production secrets with --set on the command line. Use a values file with restricted permissions or a Kubernetes Secret as described in Secrets management.

# Create namespace
kubectl create ns sure || true

# Create a values file for the initial secret
SECRET_KEY_BASE=$(openssl rand -hex 32)
cat > values-quickstart.yaml <<EOF
image:
  tag: v1.2.3
rails:
  secret:
    enabled: true
    values:
      SECRET_KEY_BASE: "$SECRET_KEY_BASE"
EOF
chmod 600 values-quickstart.yaml

# Install chart with a pinned image tag
helm upgrade --install sure sure/sure \
  -n sure \
  -f values-quickstart.yaml

Expose the app via an ingress (see configuration below) or port-forward:

kubectl port-forward svc/sure 8080:80 -n sure

Navigate to http://localhost:8080 to access Sure. After creating your initial admin account, you can control future signups from Settings > Self-Hosting > Onboarding:

Open: Anyone can create an account from the registration page.
Invite-only: Signups stay enabled, but a valid invite code is required unless a default family is configured for invite-only onboarding.
Closed: The registration page is disabled for new signups.

If you do not want additional self-service registrations, switch the instance to Closed after the initial setup.

Configuration

Using external Postgres and Redis

To use external managed databases instead of the bundled subcharts, store connection strings in a Kubernetes Secret and reference them from your values file. See Secrets management for the general pattern.

cnpg:
  enabled: false

redisOperator:
  managed:
    enabled: false

redisSimple:
  enabled: false

rails:
  extraEnv:
    DATABASE_URL:
      valueFrom:
        secretKeyRef:
          name: external-db-credentials
          key: database-url
    REDIS_URL:
      valueFrom:
        secretKeyRef:
          name: external-db-credentials
          key: redis-url

Redis Sentinel (high availability)

The OT-CONTAINER-KIT Redis Operator supports a Sentinel failover layer for production HA deployments. When you enable Sentinel mode, the chart automatically injects REDIS_SENTINEL_HOSTS and REDIS_SENTINEL_MASTER into the web and worker pods so Sidekiq can do automatic master discovery and failover.

redisOperator:
  enabled: true
  managed:
    enabled: true
  mode: sentinel             # enables RedisSentinel CR in addition to RedisReplication
  sentinel:
    enabled: true            # must be true when mode=sentinel
    masterGroupName: mymaster
  replicas: 3
  auth:
    existingSecret: sure-secrets
    passwordKey: redis-password
  persistence:
    className: longhorn
    size: 8Gi

The application receives REDIS_SENTINEL_HOSTS (comma-separated Sentinel endpoints) and REDIS_SENTINEL_MASTER instead of REDIS_URL.
Sentinel authentication uses username default by default. Override with REDIS_SENTINEL_USERNAME if needed.
Provider precedence: explicit rails.extraEnv.REDIS_URL → redisOperator.managed (with Sentinel if configured) → redisSimple.
Only one in-cluster Redis provider should be enabled at a time.

Active Record encryption keys

In self-hosted mode, Sure can derive Active Record encryption keys from SECRET_KEY_BASE automatically. If you want dedicated keys instead, provide these values through your app secret:

ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT

If you add custom encryption keys after the instance already has data, the chart’s normal migration flow is not enough to rewrite older plaintext values. db:prepare still handles schema setup and migrations, but existing rows need a one-off backfill after the app is running with the new keys:

# Safe preview first (dry-run is the default)
kubectl exec -it deploy/sure-web -- bundle exec rake security:backfill_encryption

# Perform the rewrite
kubectl exec -it deploy/sure-web -- env DRY_RUN=false bundle exec rake security:backfill_encryption

The task is idempotent, so it is safe to rerun if needed. Keep the same SECRET_KEY_BASE for an existing release unless you are restoring from a backup created with the new value. Sure derives encryption keys from SECRET_KEY_BASE when dedicated ACTIVE_RECORD_ENCRYPTION_* values are not set, so changing it can prevent lookup of encrypted fields such as user email addresses and make email/password login appear invalid. If that happens after an encryption change, restore the previous secret values first, then run the backfill task if you are intentionally moving to dedicated encryption keys.

Deployment profiles

Simple single-node

Minimal setup for development or small deployments:

encryptionEnv.enabled: true tells the chart to wire the Active Record encryption keys from your secret into the app container.
SELF_HOSTED: "true" enables self-hosted behavior inside Sure.
Replace longhorn with a storage class that exists in your cluster.

image:
  repository: ghcr.io/we-promise/sure
  tag: "v1.0.0"
  pullPolicy: IfNotPresent

rails:
  existingSecret: sure-secrets
  encryptionEnv:
    enabled: true
  settings:
    SELF_HOSTED: "true"

cnpg:
  enabled: true
  cluster:
    enabled: true
    name: sure-db
    instances: 1
    storage:
      size: 8Gi
      storageClassName: longhorn

redisOperator:
  enabled: true
  managed:
    enabled: true
  mode: standalone
  replicas: 1
  persistence:
    enabled: true
    className: longhorn
    size: 8Gi

migrations:
  strategy: job

HA k3s profile

High availability setup with multiple replicas and synchronous replication:

cnpg:
  enabled: true
  cluster:
    enabled: true
    name: sure-db
    instances: 3
    storage:
      size: 20Gi
      storageClassName: longhorn
    minSyncReplicas: 1
    maxSyncReplicas: 2
    topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: kubernetes.io/hostname
        whenUnsatisfiable: ScheduleAnyway
        labelSelector:
          matchLabels:
            cnpg.io/cluster: sure-db

redisOperator:
  enabled: true
  managed:
    enabled: true
  mode: replication
  replicas: 3
  persistence:
    enabled: true
    className: longhorn
    size: 8Gi

migrations:
  strategy: job
  initContainer:
    enabled: true

hpa:
  web:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

Secrets management

Generate strong secrets before creating the Kubernetes Secret:

openssl rand -hex 32   # SECRET_KEY_BASE
openssl rand -hex 32   # ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY
openssl rand -hex 32   # ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY
openssl rand -hex 32   # redis-password
openssl rand -hex 64   # ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT

Create a Kubernetes secret with the required credentials:

apiVersion: v1
kind: Secret
metadata:
  name: sure-secrets
type: Opaque
stringData:
  # Rails secrets
  SECRET_KEY_BASE: "__SET_SECRET__"

  # Active Record Encryption keys (required for self-hosted mode)
  ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: "__SET_SECRET__"
  ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: "__SET_SECRET__"
  ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: "__SET_SECRET__"

  # Redis password
  redis-password: "__SET_SECRET__"

  # Optional external service URLs
  database-url: "postgresql://user:pass@db.example.com:5432/sure"
  redis-url: "redis://:pass@redis.example.com:6379/0"

Apply the secret:

kubectl apply -f sure-secrets.yaml -n sure

Reference the secret in your values:

rails:
  existingSecret: sure-secrets

redisOperator:
  managed:
    enabled: true
  auth:
    existingSecret: sure-secrets
    passwordKey: redis-password

Ingress configuration

Enable ingress to expose Sure externally:

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: finance.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts: [finance.example.com]
      secretName: finance-tls

Horizontal pod autoscaling

Enable HPAs for automatic scaling based on CPU utilization:

hpa:
  web:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

  worker:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

Updating

To update to a new version of Sure:

# Update the Helm repository
helm repo update sure

# Update the deployment with a new image tag
helm upgrade sure sure/sure -n sure \
  --set image.tag=v1.2.4 \
  -f your-values.yaml

The chart will automatically run database migrations before deploying the new version.

Backup and restore

These steps cover PostgreSQL backups and restore. They do not automatically back up or restore uploaded files if your deployment stores them outside PostgreSQL.

PostgreSQL backups with CloudNativePG

CloudNativePG supports volume snapshot backups:

cnpg:
  cluster:
    backup:
      method: volumeSnapshot
      volumeSnapshot:
        className: longhorn

Manual backup

Create a manual backup of your PostgreSQL database:

# Get the primary pod name
PRIMARY_POD=$(kubectl get pod -n sure -l cnpg.io/cluster=sure-db,role=primary -o jsonpath='{.items[0].metadata.name}')

# Create a backup
kubectl exec -n sure $PRIMARY_POD -- pg_dump -U sure sure_production > backup.sql

[!NOTE] If you customized the PostgreSQL username or database name in your chart values, replace sure and sure_production in the backup and restore commands below.

Restore from backup

Make sure app traffic is stopped or the deployment is in maintenance mode.
Copy the SQL backup to the primary PostgreSQL pod:

kubectl cp backup.sql sure/$PRIMARY_POD:/tmp/backup.sql

Restore the database:

kubectl exec -n sure $PRIMARY_POD -- psql -U sure sure_production -f /tmp/backup.sql

If your deployment uses uploaded files stored outside PostgreSQL, restore those separately using the matching volume snapshot or object-storage recovery process.
Verify that the app starts cleanly and your data appears as expected.

Troubleshooting

View logs

# Web logs
kubectl logs -n sure -l app.kubernetes.io/component=web

# Worker logs
kubectl logs -n sure -l app.kubernetes.io/component=worker

# Migration job logs
kubectl logs -n sure -l job-name=sure-migrate

Check pod status

kubectl get pods -n sure

Verify database connectivity

# Test connection from web pod
kubectl exec -n sure deploy/sure-web -- rails runner "puts ActiveRecord::Base.connection.execute('SELECT 1').first"

Run Helm tests

After installation, verify the deployment:

helm test sure -n sure

Uninstall

To remove Sure from your cluster:

helm uninstall sure -n sure

This will not delete PersistentVolumeClaims. Before deleting PVCs, make sure the namespace does not contain volumes for anything other than Sure.

kubectl get pvc -n sure
kubectl delete pvc -n sure <sure-pvc-name>

Pipelock (AI agent security proxy)

Pipelock is an optional security proxy that scans AI agent traffic for secret exfiltration, prompt injection, tool poisoning, and SSRF. It runs as a separate Deployment with two listeners:

Forward proxy (port 8888): Applies destination, SSRF, rate, budget, CONNECT-header DLP, and receipt controls to HTTPS tunnels from clients that honor the proxy variables. The chart does not configure TLS interception, so encrypted bodies stay opaque.
MCP reverse proxy (port 8889): Scans inbound MCP traffic from external AI assistants.

The chart pins Pipelock 3.4.0 by tag and multi-architecture image digest. Read the Pipelock release notes before overriding that pin.

Enabling Pipelock

pipelock:
  enabled: true
  image:
    tag: "3.4.0@sha256:2e6caa43967a5ef19cacbce00188d829c1b5de1eb0ad304a51d2085f32c5694c"
  mode: balanced   # strict, balanced, or audit

This creates a separate Deployment, Service, and ConfigMap. The chart auto-injects HTTPS_PROXY, HTTP_PROXY, and NO_PROXY into web and worker pods.

Request body scanning

Request body scanning covers cleartext HTTP, reverse-proxy, and WebSocket bodies. HTTPS tunnel bodies remain opaque without TLS interception. Enabled by default with action: warn. Review findings in logs before switching to action: block.

pipelock:
  requestBodyScanning:
    enabled: true
    action: warn          # warn or block
    maxBodyBytes: 5242880 # 5 MB; fail-closed above this
    scanHeaders: true
    headerMode: sensitive # "sensitive" or "all"

Health watchdog

The wedge-detection watchdog returns 503 on /health when a subsystem heartbeat goes stale. It is enabled by default. Use exposeSubsystems: true to add per-subsystem detail to the health payload.

pipelock:
  healthWatchdog:
    enabled: true
    intervalSeconds: 2
    exposeSubsystems: true

Signed action receipts

Pipelock can write hash-chained, Ed25519-signed receipts for proxied decisions. Recording is inert until you mount both a storage volume and a signing key. Generate a key and create a secret:

pipelock signing key generate --purpose receipt-signing --out "$PWD/flight-recorder-signing.key" --id sure-k8s
kubectl create namespace sure
kubectl create secret generic sure-pipelock-receipts \
  --namespace sure \
  --from-file=flight-recorder-signing.key=./flight-recorder-signing.key

If you do not have the pipelock binary installed, generate the key with the pinned image:

docker run --rm -v "$PWD:/out" ghcr.io/luckypipewrench/pipelock:3.4.0@sha256:2e6caa43967a5ef19cacbce00188d829c1b5de1eb0ad304a51d2085f32c5694c \
  signing key generate --purpose receipt-signing --out /out/flight-recorder-signing.key --id sure-k8s

Example Helm values using an existing PVC named sure-pipelock-evidence:

pipelock:
  enabled: true
  flightRecorder:
    enabled: true
    dir: /var/lib/pipelock/evidence
    signingKeyPath: /run/secrets/pipelock/flight-recorder-signing.key
    requireReceipts: false
    redact: true
  extraVolumes:
    - name: pipelock-evidence
      persistentVolumeClaim:
        claimName: sure-pipelock-evidence
    - name: pipelock-receipt-key
      secret:
        secretName: sure-pipelock-receipts
        defaultMode: 0440
  extraVolumeMounts:
    - name: pipelock-evidence
      mountPath: /var/lib/pipelock/evidence
    - name: pipelock-receipt-key
      mountPath: /run/secrets/pipelock
      readOnly: true

Keep requireReceipts: false until you confirm receipts are being written. When set to true, allow-path requests are blocked if Pipelock cannot sign or write the receipt.

Validating your config

Pipelock includes CLI tools for config validation and deployment diagnostics. Run them from the Pipelock container or using the pinned image locally:

# Create and run a broader assessment workspace
pipelock assess init --config pipelock.yaml

# Score your config's security posture (0-100)
pipelock audit score --config pipelock.yaml

# Report whether configured protections are actually enforceable
pipelock doctor

# Explain a block and the exact config knob that applies
pipelock explain --config pipelock.yaml "https://example.com/path"

In Kubernetes, run these against the running Pipelock pod:

kubectl exec -n sure deploy/sure-pipelock -- /pipelock doctor --config /etc/pipelock/pipelock.yaml

Require Pipelock for external assistants

By default, the chart rejects an external AI assistant deployment without Pipelock:

pipelock:
  requireForExternalAssistant: true

helm template and helm install fail when rails.externalAssistant.enabled=true and pipelock.enabled=false. Set requireForExternalAssistant: false only when you accept direct external-assistant traffic without scanning.

Exposing the MCP proxy externally

Enable the Pipelock Ingress so external agents can reach the MCP reverse proxy:

pipelock:
  enabled: true
  ingress:
    enabled: true
    className: nginx
    hosts:
      - host: pipelock.example.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - hosts: [pipelock.example.com]
        secretName: pipelock-tls

Or port-forward for testing:

kubectl port-forward svc/sure-pipelock 8889:8889 -n sure

For full Pipelock configuration options, see Self-hosting with Docker and the pipelock.example.yaml reference file in the Sure repository.

Getting help

If you find bugs or have feature requests:

Read the contributing guide
Ask in the Discord
Open an issue

​Prerequisites

​Features

​Installation

​Add Helm repositories

​Quickstart (turnkey self-hosting)

​Configuration

​Using external Postgres and Redis

​Redis Sentinel (high availability)

​Active Record encryption keys

​Deployment profiles

​Simple single-node

​HA k3s profile

​Secrets management

​Ingress configuration

​Horizontal pod autoscaling

​Updating

​Backup and restore

​PostgreSQL backups with CloudNativePG

​Manual backup

​Restore from backup

​Troubleshooting

​View logs

​Check pod status

​Verify database connectivity

​Run Helm tests

​Uninstall

​Pipelock (AI agent security proxy)

​Enabling Pipelock

​Request body scanning

​Health watchdog

​Signed action receipts

​Validating your config

​Require Pipelock for external assistants

​Exposing the MCP proxy externally

​Getting help

Prerequisites

Features

Installation

Add Helm repositories

Quickstart (turnkey self-hosting)

Configuration

Using external Postgres and Redis

Redis Sentinel (high availability)

Active Record encryption keys

Deployment profiles

Simple single-node

HA k3s profile

Secrets management

Ingress configuration

Horizontal pod autoscaling

Updating

Backup and restore

PostgreSQL backups with CloudNativePG

Manual backup

Restore from backup

Troubleshooting

View logs

Check pod status

Verify database connectivity

Run Helm tests

Uninstall

Pipelock (AI agent security proxy)

Enabling Pipelock

Request body scanning

Health watchdog

Signed action receipts

Validating your config

Require Pipelock for external assistants

Exposing the MCP proxy externally

Getting help