Umami

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name my-umami-2fa-key --encoding plain -f -

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/umami \
  --version 1.5.0 --gvc GVC_NAME \
  --set app.appSecretName=APP_SECRET_NAME \
  --set postgres.config.credentialsSecretName=my-umami-db-credentials

image: ghcr.io/umami-software/umami:3.4.1 # versions before 3.4.1 are refused (Critical CVEs)

replicas: 1 # 1 = single instance; 2+ = always-on tier with zero-downtime rolling restarts

resources: # per replica
  minCpu: 100m
  maxCpu: 500m
  minMemory: 256Mi
  maxMemory: 512Mi

app:
  # Opaque secret (encoding: plain) holding the app secret, which signs auth tokens
  # and sessions. MUST EXIST BEFORE INSTALL; its value must stay stable.
  appSecretName: my-umami-app-secret
  disableTelemetry: true # opt out of Umami's anonymous usage telemetry
  twoFactorKeySecretName: "" # optional opaque secret holding the two-factor key; "" = 2FA unavailable

tracker:
  scriptName: ""      # custom tracker script path, e.g. "s.js" (dodges ad blockers); "" = default /script.js; not "recorder.js" (Umami's session-replay script)
  collectEndpoint: "" # custom collect API path, e.g. "/api/track"; "" = default /api/send

postgres: # default: single-instance PostgreSQL — set postgresHA.enabled: true (and this false) for failover
  enabled: true
  image: postgres:18
  config:
    # REQUIRED PREREQUISITE SECRET (single-instance mode) — CREATE IT BEFORE YOU
    # INSTALL. If it does not exist the deployment WEDGES silently and looks like a
    # platform fault. A `dictionary` secret holding exactly three keys: username,
    # password, database. PostgreSQL reads it once, when its data is first
    # initialized, and Umami connects with the same keys. See Prerequisites.
    credentialsSecretName: my-umami-db-credentials
  resources:
    minCpu: 250m
    maxCpu: 1
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

postgresHA: # durable HA: 3-replica Patroni store with an HAProxy leader endpoint
  enabled: false
  config:
    # REQUIRED PREREQUISITE SECRET (HA mode) — the same kind of `dictionary`
    # secret as postgres.config.credentialsSecretName above (keys: username,
    # password, database). Create it BEFORE you install.
    credentialsSecretName: my-umami-db-credentials
  replicas: 3
  image: controlplanecorporation/patroni-postgres:0.8 # pgvector 0.8.7 (CVE-2026-103484); tags 0.1-0.7 are refused
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

publicAccess:
  # false = nothing reaches Umami from the internet. Change the hardcoded admin
  # password first, then set this true — tracking needs it.
  enabled: false

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: []  # only used when type is same-gvc or workload-list

cpln port-forward RELEASE_NAME-umami 3000:3000 --gvc GVC_NAME

postgres:
  backup:
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0 # 18.1.0 = PG18, 17.1.0 = PG17
    schedule: "0 2 * * *"  # daily at 2am UTC
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws          # aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: umami/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: umami/backups
    minio:                 # any S3-compatible endpoint (e.g. an internal MinIO template)
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      credentialsSecretName: my-umami-minio-credentials # prerequisite dictionary secret, minio only
      prefix: umami/backups

postgresHA:
  backup:
    enabled: false
    mode: logical          # logical or wal-g
    resources:
      cpu: 100m
      memory: 128Mi
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *" # daily at 2am UTC
    walg:
      intervalSeconds: 21600 # every 6 hours
    provider: aws          # aws, gcp, or minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: umami/backups
    gcp:
      bucket: my-backup-bucket
      cloudAccountName: my-backup-cloudaccount
      prefix: umami/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-backup-bucket
      credentialsSecretName: my-umami-minio-credentials # prerequisite dictionary secret, minio only
      prefix: umami/backups

cpln secret reveal OLD_SECRET_NAME -o yaml   # the CURRENT values, until the upgrade deletes this secret
cpln secret create-dictionary --name RELEASE_NAME-postgres-credentials \
  --entry username='YOUR_CURRENT_USERNAME' --entry password='YOUR_CURRENT_PASSWORD' --entry database='YOUR_CURRENT_DATABASE'

ALTER EXTENSION vector UPDATE;

pgx() { cpln workload exec RELEASE_NAME-postgres-ha --gvc GVC_NAME --location LOCATION \
  --container patroni-postgres --replica "RELEASE_NAME-postgres-ha-$1" -- "${@:2}"; }
# 1. Find the leader ("role": "leader"); the other two must be "streaming" on the same "timeline"
pgx 0 curl -s localhost:8008/cluster
# 2. If the leader is not RELEASE_NAME-postgres-ha-0, move it there (N = current leader), then repeat step 1
pgx 0 curl -s -XPOST -d '{"leader":"RELEASE_NAME-postgres-ha-N","candidate":"RELEASE_NAME-postgres-ha-0"}' localhost:8008/switchover
# 3-5. Back to back: change BOTH roles on -0, put the same password in the secret, restart the members
pgx 0 psql -h 127.0.0.1 -d postgres -c "ALTER ROLE DB_USERNAME PASSWORD 'NEW_PASSWORD'; ALTER ROLE repl PASSWORD 'NEW_PASSWORD';"
cpln secret edit SECRET_NAME
cpln workload force-redeployment RELEASE_NAME-postgres-ha --gvc GVC_NAME
# 6. Once the members have restarted, confirm one leader and two "streaming" replicas on one timeline (repeat step 1)
# 7. Optional: remove the install-time password Patroni keeps in its cluster config
pgx 0 curl -s -XPATCH -d '{"postgresql":{"authentication":null}}' localhost:8008/config

pgx N curl -s -XPOST -d '{"force": true}' localhost:8008/reinitialize