--- name: Umami description: Deploy Umami analytics avoiding data loss, tracking failures, and integration issues. metadata: {"clawdbot":{"emoji":"📊","os":["linux","darwin","win32"]}} --- ## 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 `` not `` — 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