SYS.DOCS // DOCS

Deploy and Operate Umami

Umami is an open source, privacy focused web analytics platform. Edka deploys it as a managed app in your Kubernetes cluster and connects it to an existing PostgreSQL database.

Architecture

Component	Purpose	How Edka connects it
Umami app	Web analytics dashboard and event collection API	Installed from the Edka Umami chart
PostgreSQL	Stores sites, events, and account data	Select an installation, database, and user from the Databases workspace
Envoy Gateway	HTTPS access to the dashboard and tracker	Select a traffic class and hostname

Umami’s application pod holds no local state, so no persistent volume is provisioned for it.

Prerequisites

Before installing Umami, prepare:

an Edka cluster with an Envoy Gateway traffic class and managed TLS; Umami’s Gateway exposure cannot be turned off
a DNS hostname for the Umami dashboard and tracker
a managed PostgreSQL installation with a dedicated database and a user that can connect to it

See Databases and Gateway API if these are not ready yet.

Install Umami

Open your cluster and select Apps.
Find Umami and select Install.
In General, choose the Namespace, confirm the Umami Chart Version and Umami Image Tag, and decide whether Edka may automatically apply matching updates.
In Database, select the PostgreSQL Installation, PostgreSQL Database, and PostgreSQL User prepared for Umami. Edka resolves the host, port, schema, SSL settings, and password from the selection and builds the connection string.
In Configuration, review the privacy and tracker settings described below. Edka generates the App Secret automatically; there is no field to fill in.
Review Resources and Placement.
In Access, confirm the Traffic Class and enter the Hostname for the dashboard and tracker.
Select Install App and follow the operation progress until Umami is ready.

Secrets

Umami’s runtime Secret in the app namespace stores the resolved database connection string and the app secret.

Secret	Purpose	Handling
App Secret	Signs Umami authentication tokens	Generated automatically at install (64 characters); not editable; preserved across configuration updates
PostgreSQL Password	Authenticates the connection to PostgreSQL	Resolved from the selected user’s password Secret at install and on every update
PostgreSQL URL	Full PostgreSQL connection string	Built by Edka from the values above and stored in the runtime Secret

Privacy and Tracker Configuration

The Configuration tab controls Umami’s runtime behavior:

Disable Telemetry is enabled by default. It disables anonymous Umami telemetry from the self-hosted instance.
Disable Update Checks is enabled by default. It disables Umami’s built-in update check.
Tracker Script Name is an optional custom tracker script path or filename, for example stats.js.
Collect API Endpoint is an optional custom event collection endpoint, for example /api/send.
Client IP Header is an optional proxy header Umami should use for client IP detection, for example x-forwarded-for, when Umami runs behind a proxy that does not preserve the client address.

Leave the tracker and collection fields empty to use Umami’s defaults.

Gateway Hostname and Endpoints

Expose Umami via Gateway defaults to enabled and cannot be turned off, so every Umami install publishes through an Envoy Gateway traffic class. Select the Traffic Class available in the cluster and enter a Hostname that resolves through it.

After installation, Edka shows:

an internal service URL for in-cluster access to the dashboard and event collection API on port 3000
the external HTTPS URL for the dashboard and tracker

Resources and Placement

Setting	Default
CPU Request	`200m`
Memory Request	`512Mi`
CPU Limit	`1000m`
Memory Limit	`1Gi`

Umami runs as a single pod; the chart’s replica count is fixed and is not a configurable input. You can place Umami on a selected Node Pool and enable Tolerate Node Pool Taints (enabled by default) to automatically add tolerations for taints configured on that pool.

Updates

Auto-update App is disabled by default. When enabled, Auto-update Policy allows patch, minor, major, all, or a custom version pattern (default minor) for both the Umami chart version and the Umami image tag. Custom Tag Pattern appears only when the policy is set to custom, and accepts a glob: or regexp: prefixed filter. Auto-update Check controls how often Edka checks for a matching update, from every 5 minutes up to daily.

Troubleshooting

Symptom	Check
Umami install fails to build the database connection	Select a PostgreSQL installation, database, and user in the Database tab; all three are required
PostgreSQL password Secret not found	Confirm the selected PostgreSQL user’s password Secret still exists in the Databases workspace
Runtime Secret not found on update	The `<release>-config` Secret was deleted outside Edka; restore it or reinstall Umami before updating
Hostname is rejected	Enter a valid domain, for example `umami.example.com`
Dashboard or tracker unreachable	Confirm the selected Traffic Class and hostname DNS resolve; Umami’s Gateway exposure cannot be disabled
Pod stays unready	Verify PostgreSQL connectivity: host, port, database, user, password, and SSL settings