Analytics, checked 2026-10-17
Umami: Docker configuration reference
Self-hosted web analytics on Next.js with a PostgreSQL backend and optional ClickHouse for analytics queries.
At a glance
- Image:
ghcr.io/umami-software/umami - Tags:
latest,3.4.0,3.4,postgresql-latest - Licence: MIT
- Source: https://github.com/umami-software/umami
- Docs: https://docs.umami.is/docs/
Ports
| Port | What listens | Source |
|---|---|---|
3000 | HTTP listener for the dashboard, the tracker script and the collect API. Point the reverse proxy here. | source for port 3000 |
5432 (db) | PostgreSQL, reached over the internal network only. It does not need publishing to the host. | source for port 5432 |
Environment variables
| Variable | Required | What it does | Example | Source |
|---|---|---|---|---|
DATABASE_URL | Yes | Connection string for the database. The docs call it the only required variable, but the upstream compose also sets APP_SECRET. | postgresql://umami:umami@db:5432/umami | source for DATABASE_URL |
APP_SECRET | Yes | Random string that secures authentication tokens. Each installation needs its own value. | openssl rand -hex 32 | source for APP_SECRET |
TWO_FACTOR_ENCRYPTION_KEY | No | 64 character hex key required before two-factor authentication will work. Since v3.3.0. | openssl rand -hex 32 | source for TWO_FACTOR_ENCRYPTION_KEY |
CLIENT_IP_HEADER | No | HTTP header to read the visitor IP from when a proxy in front uses a non-standard header. Since v1.24.0. | CF-Connecting-IP | source for CLIENT_IP_HEADER |
COLLECT_API_ENDPOINT | No | Moves the collect endpoint off the default /api/send, which is what ad blockers match on. Since v1.34.0. | /api/collect-here | source for COLLECT_API_ENDPOINT |
DISABLE_TELEMETRY | No | Turns off the anonymous usage telemetry the application sends upstream. Since v2.0.0. | 1 | source for DISABLE_TELEMETRY |
DISABLE_LOGIN | No | Disables the login page entirely. Since v1.26.0. Only sane behind an identity gate you already trust. | 1 | source for DISABLE_LOGIN |
CORS_MAX_AGE | No | Seconds a CORS preflight is cached for. Default is 24 hours. Since v2.0.0. | 86400 | source for CORS_MAX_AGE |
Volumes that must persist
| Path | What is in it | Source |
|---|---|---|
/var/lib/postgresql/data (db) | The whole dataset. The application container itself is stateless, so this is the only thing to back up. | source for /var/lib/postgresql/data |
Behind a reverse proxy
- Route the domain to container port 3000. No websocket upgrade is needed for the dashboard. source for this reverse-proxy note
- Health endpoint is /api/heartbeat. The upstream compose healthcheck curls it every 5 seconds with 5 retries. source for this reverse-proxy note
- Behind Cloudflare or any proxy adding its own IP header, set CLIENT_IP_HEADER or every visitor logs as the proxy. source for this reverse-proxy note
- The container waits on a healthy database via depends_on, so a proxy pointed at it will 502 until Postgres reports ready. source for this reverse-proxy note
What it needs alongside it
| Dependency | Why | Source |
|---|---|---|
| PostgreSQL (ClickHouse optional) | The upstream compose file pairs the application with postgres:15-alpine. From v3 there is one image; MySQL is no longer supported. | source for PostgreSQL (ClickHouse optional) |
Release timeline
| Version | Date | Breaking | What changed | Source |
|---|---|---|---|---|
v3.4.0 | 2026-09-17 | No | Adds annotations, API keys, a read-only MCP endpoint (off unless MCP_ENABLED=1) and new analytics APIs; legacy report APIs kept. Runs schema migrations. | source for release v3.4.0 |
v3.3.1 | 2026-08-20 | No | Maintenance release. Hardens two-factor auth when TWO_FACTOR_ENCRYPTION_KEY is missing or invalid. | source for release v3.3.1 |
v3.3.0 | 2026-08-12 | Yes | Adds two-factor authentication, which needs the new TWO_FACTOR_ENCRYPTION_KEY variable set before it will work. | source for release v3.3.0 |
v3.2.0 | 2026-06-24 | No | Adds heatmaps, property reporting changes and session replay controls. | source for release v3.2.0 |
v3.1.0 | 2026-04-16 | No | Adds boards, session replay, web vitals performance tracking and a redesigned share page. | source for release v3.1.0 |
v3.0.3 | 2025-12-12 | No | Patch for the Next.js security advisory published 2025-12-11. | source for release v3.0.3 |
If it is not coming up
- ECONNREFUSED / ENOTFOUND / connection to server at "postgres" port 5432 failed
- 502 Bad Gateway (Traefik)
- Healthcheck failed / Container is unhealthy
- Self-Hosting Umami Analytics on Coolify
Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.