Umami

Overview

Umami is a privacy-first, cookieless web and product analytics platform — a self-hosted, MIT-licensed alternative to Google Analytics. This template deploys the stateless Umami v3 app tier backed by PostgreSQL, serving both the analytics dashboard and the public tracking endpoint over HTTPS. You embed a small tracking script on your site; visitor events POST back to the same workload and are stored in PostgreSQL, with no cookies and no personal data collected.

Architecture

Umami — A stateless standard workload serving the dashboard, API, and tracking/collect endpoint on port 3000. Runs a single replica by default; set replicas to 2 or more for an always-on tier with zero-downtime rolling restarts. All state lives in PostgreSQL, so replicas are independent — no clustering.
PostgreSQL (single-instance, default) — The postgres template as a subchart: the backing store for all users, websites, sessions, and events.
PostgreSQL (HA, optional) — The postgres-highly-available template instead: 3× Patroni PostgreSQL with automatic failover and an HAProxy leader endpoint, for a durable production store.

What Gets Created

Standard Umami Workload — One or more stateless replicas serving the UI, API, and tracking endpoint on port 3000.
Database Workloads — Single mode: one stateful PostgreSQL workload. HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload.
Volume Sets — The database subchart’s persistent volumes (10 GiB by default; per replica in HA mode). Umami itself has none.
Secret, Identity & Policy — A template-managed appSecret (dictionary secret) and a least-privilege policy granting the Umami identity reveal on exactly the app config secret and the active database credential secret.
Cron Backup Workload (optional) — When database backups are enabled.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

None for a default install. For optional database backups you need a bucket and access setup for one of the supported providers — see Backing Up. Install the template using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Choosing a Database Mode

Exactly one of the two backing stores must be enabled — the chart enforces this at render. Umami is wired to the active database automatically.

	`postgres` (default)	`postgresHA`
What runs	One single-replica PostgreSQL workload	3× Patroni PostgreSQL, 3× etcd, HAProxy leader endpoint
Database failover	None	Automatic (Patroni leader election)
Best for	Development and lightweight installs	Production

To switch to HA mode, set postgres.enabled: false and postgresHA.enabled: true.

Configuration

Key configuration values (see the template’s values.yaml for the complete set):

image: ghcr.io/umami-software/umami:3.2.0

replicas: 1 # 1 = proven single-instance; 2+ = always-on, zero-downtime restarts

resources: # per replica
  cpu: 500m
  memory: 512Mi
  minCpu: 100m
  minMemory: 256Mi

app:
  # Signs auth tokens; MUST be unique per install, identical across replicas,
  # and stable across restarts (changing it logs everyone out).
  appSecret: "change-me-KJ8xQ2mZraB7vN1pLwCf5tHgUeYd0sQ4" # override: openssl rand -base64 32
  disableTelemetry: true # opt out of Umami's anonymous usage telemetry

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

postgres: # default: single-instance PostgreSQL
  enabled: true
  image: postgres:18
  config:
    username: umami
    password: change-me-umami-db # change before installing
    database: umami
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)
  backup:
    enabled: false # true = scheduled backups of the analytics DB to object storage
    schedule: "0 2 * * *" # daily at 2am UTC
    provider: aws # aws | gcp | minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: umami/backups

postgresHA: # durable HA: 3-replica Patroni store with an HAProxy leader endpoint (disable postgres first)
  enabled: false
  postgres:
    username: umami
    password: change-me-umami-db # change before installing
    database: umami
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)
  backup:
    enabled: false # true = scheduled backups to object storage
    mode: logical # logical | wal-g
    provider: aws # aws | gcp | minio
    aws:
      bucket: my-backup-bucket
      region: us-east-1
      cloudAccountName: my-backup-cloudaccount
      policyName: my-backup-policy
      prefix: umami/backups

publicAccess:
  enabled: true # HTTPS dashboard + tracking endpoint via the canonical *.cpln.app endpoint

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # only used with same-gvc / workload-list

Application

image — The Umami open-source container image.
replicas — Number of stateless app-tier replicas. 1 is the proven single-instance shape; 2 or more gives an always-on tier where rolling restarts cycle one replica at a time with no downtime. Replicas are independent and share only the database and app.appSecret.
resources — CPU and memory per replica.
app.appSecret — Signs auth tokens and secures sessions. It must be unique per installation, identical across replicas, and stable across restarts — changing it logs every user out. Generate one with openssl rand -base64 32 and set it before installing.
app.disableTelemetry — When true (default), opts out of Umami’s anonymous usage telemetry.

Tracker

tracker.scriptName — Serve the tracking script under a custom path (e.g. s.js → /s.js) instead of the default /script.js. Useful for reducing ad-blocker interception.
tracker.collectEndpoint — Have the tracker POST events to a custom path (e.g. /api/track) instead of the default /api/send.

Both default to "" (standard paths). Custom paths take effect once a replica has fully booted with the new setting; a mid-rollout replica still serves the old path until it cycles.

Access

publicAccess.enabled — Serve the dashboard and tracking endpoint on the canonical *.cpln.app HTTPS endpoint (default). Keep this enabled for tracking to work — browsers must reach /script.js and /api/send. Set to false for an internal-only instance (external requests are blocked at the edge; in-GVC callers still reach it per internalAccess), which stops all public data collection.
internalAccess.type — Internal firewall scope of the Umami workload:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

Backing Store

Enable exactly one of postgres (single-instance, default) or postgresHA (HA) — see Choosing a Database Mode. In both modes, change the database password before installing (postgres.config.password / postgresHA.postgres.password).

Connecting

What	Value
Public URL	`status.canonicalEndpoint` of `{release}-umami` (`cpln workload get {release}-umami -o yaml`)
Dashboard / login	`https://<canonical>.cpln.app/login`
Tracking script	`https://<canonical>.cpln.app/script.js` (embed on your site)
Collect endpoint	`https://<canonical>.cpln.app/api/send` (where the tracker POSTs events)
Internal (same GVC)	`http://{release}-umami.{gvc}.cpln.local:3000`
Default admin	`admin` / `umami` — hardcoded; change it immediately (see Important Notes)

To start collecting data, log in, add a website in the dashboard, then paste the generated <script> tag — which loads the tracking script and POSTs to the collect endpoint — into your site’s HTML.

Backing Up

Database backups are optional and disabled by default. They cover the analytics database — the users, websites, sessions, and events that make up your Umami instance. Enable them with postgres.backup.enabled or postgresHA.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The backup runs as a scheduled job in the backing PostgreSQL store, so this is the same setup as that template.

AWS S3
Google Cloud Storage
S3-compatible (MinIO)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy that grants list/get/put/delete on your bucket (arn:aws:s3:::YOUR_BUCKET and arn:aws:s3:::YOUR_BUCKET/*), then set backup.aws.policyName to the policy’s name. The backing template’s README has the full JSON.

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a Cloud Account

If you do not have one, create a Cloud Account for your GCP project and grant its service account Storage Object Admin (roles/storage.objectAdmin) on the bucket. Set backup.gcp.cloudAccountName to its name.

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint and credentials

Set backup.minio.endpoint to the S3 API address including port, and backup.minio.accessKey / backup.minio.secretKey to credentials with access to the bucket. No Cloud Account is required — the keys authenticate directly.

In HA mode, postgresHA.backup.mode selects logical (scheduled pg_dump) or wal-g (continuous WAL archiving). The full per-provider walkthrough, including the exact IAM JSON, lives in the backing postgres / postgres-highly-available template README.

Important Notes

Change the default admin password immediately after first login. The bootstrap admin is a hardcoded admin / umami, seeded by the first database migration — there is no way to override it at install time. Change it in Settings → Profile right after installing.
Set your own app.appSecret before installing. It signs auth tokens; changing it later logs every user out. Generate one with openssl rand -base64 32.
Keep publicAccess enabled for tracking to work — browsers must reach the tracking script and collect endpoint. Disabling it silently stops all public data collection.
Ad blockers block the default /script.js and /api/send — set tracker.scriptName / tracker.collectEndpoint to custom paths to reduce blocking.
replicas ≥ 2 is recommended for production — replicas are independent and share the database and appSecret; rolling restarts cycle one at a time with no downtime.
Database volumes survive reinstalls under the same release name; uninstalling deletes them — all analytics data is lost. Use postgresHA and/or enable backups for durable production data.

External References

Umami Documentation

Official Umami documentation

Tracker Configuration

Configure the tracking script and its options

Collect API

How events are sent to the collect endpoint

Environment Variables

Umami environment variables reference

Umami Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

Choosing a Database Mode

Configuration

Application

Tracker

Access

Backing Store

Connecting

Backing Up

Important Notes

External References

Umami Documentation

Tracker Configuration

Collect API

Environment Variables

Umami Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​Choosing a Database Mode

​Configuration

​Application

​Tracker

​Access

​Backing Store

​Connecting

​Backing Up

​Important Notes

​External References

Umami Documentation

Tracker Configuration

Collect API

Environment Variables

Umami Template

Overview

Architecture

What Gets Created

Prerequisites

Choosing a Database Mode

Configuration

Application

Tracker

Access

Backing Store

Connecting

Backing Up

Important Notes

External References