Umami

Deploy Umami analytics avoiding data loss, tracking failures, and integration issues.

Install

openclaw skills install umami

Critical Configuration

HASH_SALT must never change — changing it invalidates all existing data, essentially a reset
SQLite is not supported — despite being Node.js, Umami requires PostgreSQL or MySQL
Database contains everything — all tracking data, config, users; backup only this

Tracking Script Traps

data-website-id must match Umami config exactly — wrong ID = zero data, no error shown
Script blocked by ad blockers — self-host on same domain as site to avoid blocking
Single Page Apps don't auto-track navigation — must call umami.track() on route changes
Script in <head> not <body> — late loading misses initial pageview

SPA Integration

React: call umami.track('pageview') in router effect or navigation handler
Next.js: use @umami/next package — handles app router and pages router
Vue/Nuxt: router afterEach hook with umami.track()
Check window.umami exists before calling — script may load after component mounts

Custom Events

Event names appear verbatim in dashboard — use consistent naming scheme
Properties only searchable via API — not visible in default dashboard
umami.track('event', { key: 'value' }) for properties

Self-Hosting Considerations

Low resources needed — 256MB RAM handles most sites
PostgreSQL needs more resources than Umami itself — plan accordingly
Reverse proxy required for HTTPS — Umami runs HTTP on port 3000
Backup strategy = database backup — no filesystem state to worry about

Multi-Site Setup

One Umami instance handles many sites — add in Dashboard > Settings > Websites
Each site needs unique tracking script — get from Websites settings
Share button available per site — generates public dashboard URL

Troubleshooting

Zero pageviews — check browser Network tab, verify script loads without error
Script 404 — verify CORS headers if cross-domain, or self-host on same domain
Events not appearing — check browser console for umami errors
Dashboard slow — check database performance, PostgreSQL query times

Common Mistakes

Using same website ID for dev and prod — pollutes analytics with test data
Not testing script after deploy — CDN caching or minification can break it
Expecting real-time updates — dashboard has slight delay, not instant