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 a bundled PostgreSQL store, serving the analytics dashboard and the tracking endpoint on the same port. You embed a small tracking script on your site; visitor events are posted back to the same workload and stored in PostgreSQL, with no cookies and no personal data collected. The install starts private: Umami seeds a hardcoded admin / umami account that no setting can override, so publicAccess.enabled defaults to false and you publish the install only after changing that password. Tracking collects nothing until you do — follow First Run.

This template deploys into an existing GVC that you already have — it does not create or manage a GVC. Every workload below runs in each location of that GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-umami`	Umami dashboard, API and tracking endpoint (standard, 1 replica by default, HTTP port `3000`, private by default)	—
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL store (stateful, 1 replica, port `5432`)	Default; `postgres.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled logical backup of the single-instance store (cron)	`postgres.backup.enabled: true`
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL store (stateful, 3 replicas)	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader endpoint Umami connects through (standard, port `5432`)	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-etcd`	Consensus store for the highly available database (stateful, 3 replicas)	`postgresHA.enabled: true`
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical backup of the highly available store (cron)	`postgresHA.backup.enabled: true` with `mode: logical`
Volume set	`RELEASE_NAME-pg-vs`	Single-instance database data (10 GiB by default; takes no scheduled snapshots; a final snapshot is taken when the volume set is deleted and kept 7 days)	Default; `postgres.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	Highly available database and consensus-store data (10 GiB per replica by default)	`postgresHA.enabled: true`
Secret	The name in `postgres.config.credentialsSecretName` (HA mode: `postgresHA.config.credentialsSecretName`), default `my-umami-db-credentials`	Database credentials (`username`, `password`, `database`), created by this chart from `postgres.credentials.*` and read by Umami and the active database	—
Secret	`RELEASE_NAME-etcd-startup`, `RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-wal-g-backup-script`	Startup scripts of the highly available database tier	`postgresHA.enabled: true`
Secret	`RELEASE_NAME-postgres-config`	Non-sensitive backup settings of the highly available database	`postgresHA.backup.enabled: true`
Identity / Policy	`RELEASE_NAME-umami-identity`, `RELEASE_NAME-umami-policy`	`reveal` on exactly two secrets: your app secret and the database credentials secret	—
Identity / Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	The single-instance database’s own identity and policy	Default; `postgres.enabled: true`
Identity / Policy	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	The highly available database tier’s own identities and policies	`postgresHA.enabled: true`

Umami itself has no volume set — every user, website, session and event lives in PostgreSQL. The app secret is a prerequisite secret you create yourself; the chart references it by name and never creates, modifies or deletes it.

Prerequisites

One opaque secret must exist before you install. Secrets are org-level, so no --gvc flag is involved.

Create the app secret

The app secret signs Umami’s auth tokens and sessions — anyone holding it can forge a login — so it is never a Helm value and never lands in the release. Generate a random value and store it as the secret’s payload:

printf '%s' "$(openssl rand -base64 32)" | cpln secret create-opaque --name APP_SECRET_NAME --encoding plain -f -

Keep it for the life of the install: changing it logs every user out. Set app.appSecretName to this name.

Choose the database password

The bundled database’s credentials are internal plumbing: this chart writes postgres.credentials.username, postgres.credentials.password and postgres.credentials.database into a dictionary secret it creates, and both Umami and the database read it. Nothing to create — but the password ships as the placeholder change-me-umami-db, so set postgres.credentials.password to a value of your own before installing. This applies in both database modes.

A missing app secret wedges the install rather than failing it. cpln helm install reports success and every resource is created, but the Umami container never starts — so cpln logs returns zero lines. The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-umami --gvc GVC_NAME -o yaml

The message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

It is get-deployments — plain cpln workload get has no versions key. Create the missing secret and the deployment recovers on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-umami --gvc GVC_NAME to skip the wait.

Optional database backups need a bucket and access setup on AWS S3, Google Cloud Storage or an S3-compatible server, and S3-compatible servers additionally need a dictionary secret with the bucket keys — see Backing Up.

Installation

Once the app secret exists, install the template into your GVC, naming the secret and replacing the database password placeholder:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/umami \
  --version 1.3.1 --gvc GVC_NAME \
  --set app.appSecretName=APP_SECRET_NAME \
  --set postgres.credentials.password='YOUR-STRONG-DB-PASSWORD'

Keep these settings in a values file (--values) rather than --set if you do not want the database password in your shell history — and because every later upgrade must pass them again. If you run more than one release of this template in the same org, also give each its own postgres.config.credentialsSecretName — see Backing Store.

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

Configuration

Application

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

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

Replicas are independent — they share only the database and the app secret, so a session opened against one replica is honored by the others.

Tracker

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

Custom paths are aliases, not replacements: the default /script.js and /api/send keep working. They help because your site loads a path ad blockers do not recognise. The custom collect path is baked into the script Umami serves, so the snippet you embed picks it up automatically.

Backing Store

Enable exactly one of the two stores — the chart refuses to render with both or neither. Umami is wired to whichever is active.

postgres: # default: single-instance PostgreSQL — set postgresHA.enabled: true (and this false) for failover
  enabled: true
  image: postgres:18
  credentials: # this chart builds the database credentials secret from these
    username: umami
    password: change-me-umami-db # change before installing
    database: umami
  config:
    # name of the dictionary secret this chart CREATES; org-wide, so unique per release
    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:
    # the secret name used in HA mode; still built from postgres.credentials.* above
    credentialsSecretName: my-umami-db-credentials
  replicas: 3
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

Choosing a Database Mode

	`postgres` (default)	`postgresHA`
What runs	One single-replica PostgreSQL workload	3 Patroni PostgreSQL replicas, 3 etcd replicas, an HAProxy leader endpoint
Database failover	None — a failed node is rescheduled onto the same volume	Automatic leader election
Best for	Most installs — analytics can tolerate a few minutes of downtime	Installs where the dashboard and collection must stay up through a database failure

To use HA mode on a new install, set postgres.enabled: false and postgresHA.enabled: true. The credentials still come from postgres.credentials.* in both modes. Switching an existing release between modes does not move data — the other store starts empty. Secret names are org-wide, so if you run more than one release of this template in the same org, give each its own credentials secret name — postgres.config.credentialsSecretName, or postgresHA.config.credentialsSecretName in HA mode. A second release left on the default name is refused at install and creates nothing; the first release is unaffected. Database backups are configured under postgres.backup / postgresHA.backup — see Backing Up.

Access

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

`internalAccess.type`	Who inside Control Plane can reach Umami
`none`	No workload
`same-gvc`	Every workload in the same GVC (default)
`same-org`	Every workload in the org
`workload-list`	Only the workloads listed in `internalAccess.workloads`

Tracking collects nothing while publicAccess.enabled is false — browsers on the sites you track must reach the tracking script and the collect endpoint. Turn it on once the admin password is changed. An access change takes a few minutes to take effect, so re-test rather than trusting the first response.

Connecting

What	Address	Notes
Dashboard (public)	`status.canonicalEndpoint` of `RELEASE_NAME-umami`, then `/login`	`cpln workload get RELEASE_NAME-umami --gvc GVC_NAME -o yaml`; present while `publicAccess.enabled` is `true`
Tracking script	`https://CANONICAL_ENDPOINT/script.js` (or your `tracker.scriptName`)	Must be the public address — the browsers of your visitors load it
Collect endpoint	`https://CANONICAL_ENDPOINT/api/send` (or your `tracker.collectEndpoint`)	Where the tracker posts events; public for the same reason
Dashboard (private)	`http://localhost:3000` through `cpln port-forward`	Works with public access off — see the command below
Internal	`http://RELEASE_NAME-umami.GVC_NAME.cpln.local:3000`	Reachable per `internalAccess.type`; for server-side event tracking from your own workloads
Admin login	`admin` / `umami` until you change it	Hardcoded by Umami — change it before publishing, see First Run
Database credentials	The secret named by `postgres.config.credentialsSecretName` (HA mode: `postgresHA.config.credentialsSecretName`)	`cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml`; keys `username`, `password`, `database`

CANONICAL_ENDPOINT is the host of status.canonicalEndpoint. Open a tunnel to the dashboard from your machine — this works whether or not public access is on:

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

Then confirm the app answers with curl -sS http://localhost:3000/api/heartbeat. The heartbeat does not touch the database, so a 200 there proves only that the app tier is up; loading the dashboard is the check that the database is reachable too.

First Run

Umami’s bootstrap admin is a hardcoded admin / umami, seeded by its first database migration and published in Umami’s own documentation. The install therefore starts private, and you publish it once the password is changed.

Install with public access off

Install as shown in Installation, leaving publicAccess.enabled at its default false. Wait until the workload reports ready:

cpln workload get-deployments RELEASE_NAME-umami --gvc GVC_NAME -o yaml

Open the dashboard through a tunnel

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

cpln port-forward is a top-level command, not a subcommand of cpln workload. Open http://localhost:3000/login in a browser and sign in as admin / umami.

Change the admin password

In the dashboard, open Settings → Profile and change the password. From then on the old password is rejected.

Publish the dashboard and tracking endpoint

Upgrade the release with publicAccess.enabled=true, passing the same app secret name and database password you installed with (or the same values file):

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/umami \
  --version 1.3.1 --gvc GVC_NAME \
  --set app.appSecretName=APP_SECRET_NAME \
  --set postgres.credentials.password='YOUR-STRONG-DB-PASSWORD' \
  --set publicAccess.enabled=true

Upgrading through the marketplace UI is the alternative. Allow a few minutes for public access to take effect, then read the endpoint with cpln workload get RELEASE_NAME-umami --gvc GVC_NAME -o yaml.

Add your website and embed the tracker

In the dashboard, add a website, then paste the generated <script> tag into the HTML of your site. It loads the tracking script from the public address and posts events to the collect endpoint.

The publishing upgrade is the first upgrade after the install, and it can restart the bundled database even though no database value changed. Expect Umami to be briefly unreachable while the database comes back; this is not a failed upgrade — do not roll back. Confirm recovery by loading the dashboard rather than by /api/heartbeat, which answers even while the database is down.

Operations

Backing Up

Database backups are optional and disabled by default. They cover everything that makes up your Umami instance — users, websites, sessions and events. They are a pass-through to the bundled database template, which runs the backup as a scheduled job; enable them on whichever store is active and complete the storage setup for your provider before installing or upgrading with them on. Single-instance mode:

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

HA mode — the same providers, plus a choice of backup mode:

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

AWS S3
Google Cloud Storage
S3-compatible (MinIO)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region on the active store 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 scoped to your bucket, then set backup.aws.policyName to its name:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:ListBucket"], "Resource": "arn:aws:s3:::BUCKET_NAME" },
    { "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"], "Resource": "arn:aws:s3:::BUCKET_NAME/*" }
  ]
}

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket on the active store 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 the bucket on your server. Set backup.minio.bucket to its name and backup.minio.endpoint to the S3 API address including the port. No cloud account is required.

Create the credentials secret

A dictionary secret holding the keys accessKey and secretKey. It must exist before you install or upgrade with backups on:

cpln secret create-dictionary --name MINIO_SECRET_NAME \
  --entry accessKey=MINIO_ACCESS_KEY \
  --entry secretKey='MINIO_SECRET_KEY'

Set backup.minio.credentialsSecretName on the active store to this name.

Restoring a Backup

No restore path has been rehearsed against this template. A restore goes into the database, not into Umami, and follows the bundled database template — rehearse it against a scratch release before you depend on it. Restoring from a volume set snapshot is likewise unverified here.

Use the procedure on the postgres page in single-instance mode, or the postgres-highly-available page in HA mode, with these Umami-specific values:

The database workload is RELEASE_NAME-postgres (single-instance) or RELEASE_NAME-postgres-ha-proxy (HA mode — always go through the leader endpoint).
The username, password and database name are the keys of the credentials secret: cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml.
The Umami container has neither psql nor a cloud CLI, so run the restore from a client that can reach both the bucket and the database — your own machine with a cpln port-forward to the database workload open, for example.
Restore into an empty database and keep Umami from writing until the replay has finished; replaying into a database Umami has already migrated collides with the existing schema.

The restored data carries its own users, so after a restore you sign in with the passwords stored in the backup, not admin / umami.

Upgrading From 1.0.0

Version 1.0.0 did not compact the etcd cluster inside the bundled highly available database, so etcd’s backend grows with time alone and goes read-only once it reaches its quota — taking PostgreSQL failover with it. Only installs running the HA database are affected (postgresHA.enabled). Upgrading to 1.0.1 or later turns compaction on: that stops further growth but cannot shrink a backend that has already grown, and a cluster that has already raised a NOSPACE alarm needs operator recovery rather than an upgrade. See etcd History Compaction.

Upgrading From 1.0.1

Version 1.1.0 is a security release that renames three values. Carrying a 1.0.1 values file forward fails at render with a message naming the replacement, so nothing silently reverts to a default:

1.0.1	1.1.0 and later	Why
`app.appSecret`	`app.appSecretName`	The app secret is now a prerequisite opaque secret you create — see Prerequisites. Put the same value you used before into the new secret, or every user is logged out
`resources.cpu`	`resources.maxCpu`	The block exposes both a reservation and a limit
`resources.memory`	`resources.maxMemory`	Same

publicAccess.enabled also changed its default to false. An upgrade that does not set it explicitly makes the install private and stops data collection — pass publicAccess.enabled=true once the admin password is changed.

Upgrading From 1.1.0

Version 1.2.0 moved the single-instance database credentials. Carrying the old keys forward fails at render:

1.1.0	1.2.0 and later
`postgres.config.username`, `postgres.config.password`, `postgres.config.database`	`postgres.credentials.username`, `postgres.credentials.password`, `postgres.credentials.database`
`postgres.backup.minio.accessKey`, `postgres.backup.minio.secretKey`	A dictionary secret holding `accessKey` and `secretKey`, named by `postgres.backup.minio.credentialsSecretName`

Move the three credential values unchanged — the database was initialised with them. The error message comes from the bundled database (config.username was REMOVED in postgres 3.4.0) and tells you to create a credentials secret yourself; ignore that part — this template creates it from postgres.credentials.*. The MinIO keys, by contrast, are a real prerequisite secret: create it as shown in Backing Up.

Upgrading From 1.2.0

Version 1.3.0 moved the HA database credentials onto the same chart-created secret as single-instance mode. Carrying the old block forward fails at render with the postgres block was REMOVED in 2.5.0. The three username, password and database values that sat in a postgres block under postgresHA now come from postgres.credentials.username, postgres.credentials.password and postgres.credentials.database, and this chart writes them into the secret named by postgresHA.config.credentialsSecretName. Delete that block from your values and set postgres.credentials.* to the same values it held — the HA database was initialised with them. Do not create the credentials secret yourself. This path has not been rehearsed on an existing HA install; take a backup before upgrading. Single-instance installs need no action.

Upgrading From 1.3.0

Version 1.3.1 moved the HA database’s MinIO backup keys into a prerequisite secret. With HA-mode MinIO backups on, the old accessKey and secretKey values under postgresHA.backup.minio now fail at render: create a dictionary secret holding accessKey and secretKey as shown in Backing Up and set postgresHA.backup.minio.credentialsSecretName to its name. No other install needs action.

Scaling and Availability

The app tier scales with replicas. It is stateless — replicas share only the database and the app secret — so 2 or more gives an always-on tier whose rolling restarts cycle one replica at a time.
The database is the availability limit. In single-instance mode a database restart makes the dashboard and collection briefly unavailable; set postgresHA.enabled: true on a new install for automatic failover.
The first helm upgrade after an install can restart the bundled database even when no database value changed.
Uninstall deletes every volume set the chart created, so all analytics data is lost and does not survive a reinstall. The GVC is yours and is left alone, and your app secret survives. Enable backups if the data matters.

Troubleshooting

The Umami workload sits at 0 replicas after install while helm reported success

Symptom: cpln helm install succeeded, but RELEASE_NAME-umami shows no containers and cpln logs returns nothing.Cause: The secret named by app.appSecretName does not exist. The deployment pauses on the unresolved reference.Fix: Read the message naming the secret, then create it as shown in Prerequisites:

cpln workload get-deployments RELEASE_NAME-umami --gvc GVC_NAME -o yaml

The message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Once the secret exists the deployment recovers on its own within several minutes, or run cpln workload force-redeployment RELEASE_NAME-umami --gvc GVC_NAME to skip the wait.

The dashboard shows no visitors

Symptom: The website is added and the tracker is embedded, but no pageviews arrive.Cause: Most often publicAccess.enabled is still false, so browsers cannot reach the tracking script or the collect endpoint — or the embedded script points at an address other than the public canonical endpoint. Ad blockers also block the default /script.js and /api/send.Fix: Set publicAccess.enabled=true (see First Run), confirm the <script> tag uses the public address, and set tracker.scriptName / tracker.collectEndpoint to custom paths to reduce ad-blocker interception.

Render fails with enable exactly one backing store

Symptom: The install stops with umami: enable exactly one backing store — set either postgres.enabled or postgresHA.enabled to true, not both, or the variant naming postgres.enabled (default) or postgresHA.enabled (durable HA).Cause: Both postgres.enabled and postgresHA.enabled are true, or both are false.Fix: Enable exactly one — see Choosing a Database Mode. For HA mode set postgres.enabled: false together with postgresHA.enabled: true.

A second release is refused because a resource is managed by a different release

Symptom: Installing a second release of this template in the same org fails with cannot be updated because it is being managed by a different release, naming the database credentials secret, and creates nothing.Cause: Secret names are org-wide, and both releases are trying to create the same credentials secret (default my-umami-db-credentials). The first release owns it.Fix: Give the new release its own postgres.config.credentialsSecretName (or postgresHA.config.credentialsSecretName in HA mode) and install again. The first release is unaffected.

Every user is logged out after a change

Symptom: All dashboard sessions end at once and everyone has to sign in again.Cause: The payload of the secret named by app.appSecretName changed, or app.appSecretName now points at a different secret. Existing tokens were signed with the old value.Fix: Nothing is lost — users sign in again. To avoid it, keep the app secret stable for the life of the install.

Upgrade fails with a key that was REMOVED or RENAMED

Symptom: helm upgrade stops at render with app.appSecret was removed in 1.1.0, resources.cpu was renamed to resources.maxCpu, config.username was REMOVED in postgres 3.4.0, the postgres block was REMOVED in 2.5.0, or backup.minio.accessKey and backup.minio.secretKey were REMOVED.Cause: Your values still carry a key that moved in template versions 1.1.0 to 1.3.1. The existing release is left untouched and running.Fix: Follow the matching migration note above — Upgrading From 1.0.1, Upgrading From 1.1.0, Upgrading From 1.2.0 or Upgrading From 1.3.0 — keeping the credentials the database already uses. Do not create a database credentials secret yourself; this template creates it.

Important Notes

Create the app secret before installing, and change postgres.credentials.password from its change-me placeholder. A missing app secret does not fail the install — the workload waits on it with no logs.
Change the hardcoded admin / umami password before turning public access on — follow First Run in order.
Tracking collects nothing until publicAccess.enabled is true, and the tracking script must be loaded from the public address.
Keep the app secret stable — changing it logs every user out. It is not owned by the release: it survives helm uninstall and must be deleted manually.
Pass the same app secret name and database password on every upgrade — a values file is the simplest way.
Give each release its own credentialsSecretName — secret names are org-wide, and a second release on the default name is refused at install.
Uninstall deletes the database volume sets — enable backups if the analytics data matters.

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

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Application

Tracker

Backing Store

Choosing a Database Mode

Access

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.0

Upgrading From 1.0.1

Upgrading From 1.1.0

Upgrading From 1.2.0

Upgrading From 1.3.0

Scaling and Availability

Troubleshooting

Important Notes

External References

Umami Documentation

Tracker Configuration

Collect API

Environment Variables

Umami Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Application

​Tracker

​Backing Store

​Choosing a Database Mode

​Access

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Upgrading From 1.0.0

​Upgrading From 1.0.1

​Upgrading From 1.1.0

​Upgrading From 1.2.0

​Upgrading From 1.3.0

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Umami Documentation

Tracker Configuration

Collect API

Environment Variables

Umami Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Application

Tracker

Backing Store

Choosing a Database Mode

Access

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.0

Upgrading From 1.0.1

Upgrading From 1.1.0

Upgrading From 1.2.0

Upgrading From 1.3.0

Scaling and Availability

Troubleshooting

Important Notes

External References