Umami

Deploy Umami on Kubernetes as a privacy-first web analytics platform. The chart uses the official ghcr.io/umami-software/umami:3.1.0 image and supports a quick bundled PostgreSQL install as well as production setups with external PostgreSQL, Gateway API or Ingress, External Secrets Operator, dual-stack Service fields, NetworkPolicy, PodDisruptionBudget, S3-compatible backups, and structured Umami runtime options.

Umami tracks page views, sessions, events, and website analytics without requiring third-party analytics services. The application stores its state in PostgreSQL and exposes a lightweight tracker script that your websites load from the Umami instance.

Key Features

• Umami 3.1.0 - aligned with the current HelmForge chart appVersion and validated with the HelmForge k3d runtime gate.
• PostgreSQL first - bundled HelmForge PostgreSQL subchart for quick starts or external PostgreSQL for production.
• External database preparation - optional init container can run CREATE EXTENSION IF NOT EXISTS pgcrypto; with an admin Secret.
• Custom initialization - user-defined init containers can prepare shared volumes, such as GeoIP databases, before Umami starts.
• Structured runtime settings - telemetry, updates, bot detection, SSL, client IP header, collect endpoint, CORS, frame allowlists, and tracker script name.
• Secret management - inline values, existing Kubernetes Secrets, or external-secrets.io/v1 resources for APP_SECRET, database password, and S3 credentials.
• Routing choices - Ingress or Kubernetes Gateway API HTTPRoute.
• Dual-stack Service - optional ipFamilyPolicy and ipFamilies fields.
• Production controls - NetworkPolicy, PodDisruptionBudget, scheduling controls, resource settings, and disabled ServiceAccount token mount by default.
• S3 backup - scheduled PostgreSQL pg_dump uploaded to S3-compatible object storage.

Architecture

Installation

HTTPS repository:

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install umami helmforge/umami --namespace umami --create-namespace

OCI registry:

helm install umami oci://ghcr.io/helmforgedev/helm/umami --namespace umami --create-namespace

Default local access:

kubectl port-forward -n umami svc/umami-umami 3000:80

Open http://localhost:3000/ and sign in with Umami’s upstream initial credentials:

• Username: admin
• Password: umami

Development vs Production

The default chart values are intentionally simple and development-friendly:

• postgresql.enabled=true
• replicaCount=1
• generated APP_SECRET and PostgreSQL password
• ClusterIP Service only
• no public ingress or Gateway API route
• no NetworkPolicy or PDB
• telemetry and update checks disabled

This is useful for local clusters, demos, and CI smoke tests. For production, use a stable APP_SECRET, external or operator-managed PostgreSQL, TLS termination, resource requests and limits, backup or database-native backup, and NetworkPolicy rules aligned with your cluster networking.

Deployment Examples

# values.yaml - development install with bundled PostgreSQL
postgresql:
  enabled: true

umami:
  appSecret: 'replace-with-a-stable-secret'

replicaCount: 2

umami:
  existingSecret: umami-app
  existingSecretKey: app-secret
  forceSSL: true
  clientIpHeader: x-forwarded-for
  trackerScriptName: stats
  collectApiEndpoint: /api/send

postgresql:
  enabled: false

database:
  external:
    host: postgres-primary.database.svc.cluster.local
    port: '5432'
    name: umami
    username: umami
    existingSecret: umami-db
    existingSecretPasswordKey: database-password
    init:
      enabled: true
      adminUsername: postgres
      adminExistingSecret: postgres-admin

resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    memory: 512Mi

pdb:
  enabled: true
  minAvailable: 1

networkPolicy:
  enabled: true
  ingress:
    allowSameNamespace: true
  egress:
    enabled: true
    allowDNS: true
    allowSameNamespaceDatabase: true
    allowHTTPS: true

postgresql:
  enabled: false

database:
  external:
    host: postgres-primary.database.svc.cluster.local
    port: '5432'
    name: umami
    username: umami
    existingSecret: umami-db
    existingSecretPasswordKey: database-password
    init:
      enabled: true
      image: docker.io/library/postgres:18-alpine
      adminUsername: postgres
      adminExistingSecret: postgres-admin
      adminExistingSecretPasswordKey: postgres-password
      sql: |
        CREATE EXTENSION IF NOT EXISTS pgcrypto;

gatewayAPI:
  enabled: true
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
  hostnames:
    - analytics.example.com

umami:
  forceSSL: true
  clientIpHeader: x-forwarded-for

postgresql:
  enabled: false

externalSecrets:
  enabled: true
  apiVersion: external-secrets.io/v1
  secretStoreRef:
    name: platform-secrets
    kind: ClusterSecretStore
  app:
    enabled: true
    targetName: umami-app
    appSecretRemoteRef:
      key: prod/umami/app
      property: appSecret
  database:
    enabled: true
    targetName: umami-db
    passwordRemoteRef:
      key: prod/umami/database
      property: password

backup:
  enabled: true
  schedule: '0 3 * * *'
  s3:
    endpoint: https://s3.example.com
    bucket: umami-backups
    prefix: production
    existingSecret: umami-backup-s3

Routing

Use Gateway API when your cluster has a Gateway controller and shared listeners:

gatewayAPI:
  enabled: true
  parentRefs:
    - name: public-gateway
      namespace: gateway-system
  hostnames:
    - analytics.example.com

Use Ingress when your platform standardizes on networking.k8s.io/v1 Ingress:

ingress:
  enabled: true
  ingressClassName: traefik
  hosts:
    - host: analytics.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: umami-tls
      hosts:
        - analytics.example.com

Service Dual Stack

The Service supports Kubernetes dual-stack fields:

service:
  ipFamilyPolicy: PreferDualStack
  ipFamilies:
    - IPv4
    - IPv6

Dual stack only works when the cluster, CNI, and Service CIDRs are configured for IPv4 and IPv6.

Custom Initialization

Use extraInitContainers with extraVolumes and extraVolumeMounts when Umami needs files prepared before the application starts, such as a GeoIP database or organization-owned assets:

extraVolumes:
  - name: geoip
    emptyDir: {}

extraInitContainers:
  - name: download-geoip
    image: docker.io/library/busybox:1.37
    command:
      - sh
      - -ec
    args:
      - wget -O /geoip/GeoLite2-City.mmdb https://example.com/GeoLite2-City.mmdb
    volumeMounts:
      - name: geoip
        mountPath: /geoip

extraVolumeMounts:
  - name: geoip
    mountPath: /app/geoip

Custom init containers run after the chart’s built-in database readiness check and optional external database preparation. Pin downloads to trusted URLs or use an internal artifact mirror for reproducible installs.

Umami Runtime Settings

Use umami.extraEnv for upstream settings that are not yet modeled directly by the chart.

Secrets

The chart can create generated Secrets, consume existing Kubernetes Secrets, or render External Secrets Operator resources. For production, prefer a stable APP_SECRET stored outside the Helm release:

umami:
  existingSecret: umami-app
  existingSecretKey: app-secret

NetworkPolicy

NetworkPolicy is opt-in because egress needs vary by platform:

networkPolicy:
  enabled: true
  ingress:
    allowSameNamespace: true
  egress:
    enabled: true
    allowDNS: true
    allowSameNamespaceDatabase: true
    databasePort: 5432
    allowHTTPS: true

When PostgreSQL, S3, OIDC, or other integrations live outside the namespace, add explicit extraTo peers for your CNI and network model.

Backup

The backup CronJob runs pg_dump against the Umami PostgreSQL database and uploads the archive to S3-compatible storage. It protects Umami users, websites, dashboards, events, session replay data, shares, and related PostgreSQL state.

Configuration Reference

Core

Image

Database

Service, Ingress, Gateway, and PDB

External Secrets

Probes, Security, and Scheduling

Common Issues

Upgrade Notes

Umami 3.x includes schema migrations for newer analytics features. Back up PostgreSQL before upgrading live deployments, especially when moving from Umami 2.x.

The chart version 2.0.0 is a breaking modernization release. Review production values for renamed or newly structured settings, External Secrets behavior, Gateway API, NetworkPolicy, and backup credentials before upgrading.

More Information

• Umami Official Website
• Umami Documentation
• Umami Environment Variables
• Umami GitHub Repository
• HelmForge Umami Chart Source