Umami Setup & Implementation: Self-Hosted Install

How to install and self-host Umami analytics with Docker or Node.js. Covers PostgreSQL/MySQL database setup, tracking script deployment, multi-site...

Umami Setup and Implementation Guide

Umami is a simple, fast, privacy-focused alternative to Google Analytics. It's open-source, self-hostable, and designed to provide essential website analytics without compromising visitor privacy. Unlike traditional analytics platforms, Umami doesn't use cookies, doesn't track personal information, and complies with GDPR, CCPA, and other privacy regulations out of the box.

Why Choose Umami?

Privacy-First Philosophy:

No cookies or local storage
No personal data collection
No cross-site tracking
GDPR and CCPA compliant by design
Anonymous visitor tracking only

Simple and Lightweight:

Minimal script size (< 2KB gzipped)
Fast page load impact
Clean, intuitive dashboard
Essential metrics without complexity
No overwhelming data overload

Self-Hosted or Cloud:

Host your own instance for complete data ownership
Use Umami Cloud for managed hosting
Full control over data retention and access
Export data anytime

Open Source:

Transparent codebase
Active community development
No vendor lock-in
Free to use and modify

Quick Start

The fastest way to get Umami running:

Step 1: Choose Hosting

Umami Cloud (Easiest):

Visit cloud.umami.is
Create account
Add website
Get tracking code

Self-Hosted (Maximum Control):

Deploy to Vercel, Railway, or Docker
Set up PostgreSQL or MySQL database
Create admin account
Add website in dashboard

Step 2: Install Tracking Script

<script async src="https://your-umami.com/script.js" data-website-id="YOUR_WEBSITE_ID"></script>

Step 3: Verify Installation

Visit your website
Check Umami dashboard "Realtime" view
See your visit appear

That's it! You're now tracking analytics privately.

Setup Workflow

Phase 1: Account Setup (5-10 minutes)

Cloud Option:

Sign up at cloud.umami.is
Confirm email
Log into dashboard
Create your first website

Self-Hosted Option:

Choose deployment platform
Fork Umami repository or use Docker
Connect database (PostgreSQL recommended)
Deploy application
Create admin account
Access your Umami dashboard

Phase 2: Website Configuration (5 minutes)

Add Website in Dashboard:

Click "Add Website"
Enter website name (e.g., "My Blog")
Enter domain (e.g., "example.com")
Save website

Copy Tracking Code:

Click on your website
Go to "Settings"
Find "Tracking Code" section
Copy the script tag

Example Tracking Code:

<script async src="https://analytics.example.com/script.js" data-website-id="abc-123-def-456"></script>

Phase 3: Implementation (10-30 minutes)

For Simple HTML Sites:

Add script to <head> or before </body> in your HTML template:

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
  <script async src="https://analytics.example.com/script.js" data-website-id="abc123"></script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

For WordPress:

Install "Insert Headers and Footers" plugin
Add Umami script to header
Save changes

Or use theme's header.php:

<?php wp_head(); ?>
<script async src="https://analytics.example.com/script.js" data-website-id="abc123"></script>

For React/Next.js:

npm install @umami/tracker

// _app.js or layout.js
import umami from '@umami/tracker';

umami.init({
  websiteId: process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID,
  hostUrl: 'https://analytics.example.com'
});

For Vue.js:

// main.js
import umami from '@umami/tracker';

umami.init({
  websiteId: import.meta.env.VITE_UMAMI_WEBSITE_ID,
  hostUrl: 'https://analytics.example.com'
});

Phase 4: Verification (5 minutes)

Test Tracking:

Open your website in a browser
Open browser DevTools console
Type console.log(window.umami)
Should see umami object (not undefined)

Check Dashboard:

Go to Umami dashboard
Select your website
View "Realtime" tab
Your visit should appear within seconds

Verify Events:

// In browser console
umami.track('test_event', { test: true });

Then check "Events" tab in dashboard for test_event.

Understanding the Dashboard

Overview Tab:

Pageviews: Total pages viewed
Unique Visitors: Distinct visitors (privacy-preserving)
Bounce Rate: Single-page visits
Average Visit Time: Time spent on site

Realtime Tab:

See visitors currently on your site
Live pageview updates
Current page being viewed

Pages Tab:

Most visited pages
Pageviews per page
Entry and exit pages

Referrers Tab:

Traffic sources
Direct vs. referral traffic
Top referring domains

Events Tab:

Custom tracked events
Event counts and metadata
Filter by event type

Devices/Browsers/OS:

Visitor technology breakdown
Mobile vs. desktop usage
Browser market share for your site

Countries/Languages:

Geographic distribution
Language preferences
Regional insights

Configuration Options

Website Settings:

Website Name: My Blog
Domain: example.com
Enable Share URL: Yes/No
Time Zone: America/New_York

Tracking Code Customization:

<!-- Basic -->
<script async src="https://analytics.example.com/script.js" data-website-id="abc123"></script>

<!-- With domain restriction -->
<script async
  src="https://analytics.example.com/script.js"
  data-website-id="abc123"
  data-domains="example.com,www.example.com">
</script>

<!-- Disable auto-tracking -->
<script async
  src="https://analytics.example.com/script.js"
  data-website-id="abc123"
  data-auto-track="false">
</script>

Environment Configuration:

const umamiConfig = {
  // Don't track in development
  enabled: process.env.NODE_ENV === 'production',

  // Use different website IDs for staging/production
  websiteId: process.env.VERCEL_ENV === 'production'
    ? process.env.UMAMI_PROD_ID
    : process.env.UMAMI_STAGING_ID,

  hostUrl: 'https://analytics.example.com'
};

if (umamiConfig.enabled) {
  umami.init(umamiConfig);
}

Common Setup Patterns

Multi-Site Setup:

Track multiple websites from one Umami instance:

Umami Instance: analytics.example.com

Website 1: Main Site (example.com)
  - Website ID: abc123

Website 2: Blog (blog.example.com)
  - Website ID: def456

Website 3: Shop (shop.example.com)
  - Website ID: ghi789

Each gets its own tracking code with unique website ID.

Team Access:

Share access with team members:

Go to "Settings" → "Users"
Add user email
Set permissions:
- Admin: Full access to all websites
- User: View-only access
User receives invitation email

Data Sharing:

Create public dashboards:

Go to website settings
Enable "Share URL"
Copy public URL
Share with stakeholders

Public URL shows analytics without requiring login.

Advanced Features

Custom Events:

Track specific user actions:

// Button click
document.getElementById('signup-btn').addEventListener('click', () => {
  umami.track('signup_button_click', {
    location: 'hero_section'
  });
});

// Purchase
umami.track('purchase', {
  product: 'Pro Plan',
  value: 99,
  currency: 'USD'
});

// Download
umami.track('whitepaper_download', {
  title: 'SEO Guide 2024'
});

Goals and Conversions:

While Umami doesn't have built-in "goals", use custom events:

// Track sign ups as events
function handleSignup() {
  umami.track('signup_completed', {
    plan: 'free',
    source: 'landing_page'
  });

  // Your signup logic
}

Then filter Events tab by event name to see conversion counts.

Filtering and Segments:

Dashboard filters:

Date range (last 24 hours, 7 days, 30 days, custom)
Device type (desktop, mobile, tablet)
Browser
OS
Country

Combine filters to create segments:

"Mobile users from US"
"Chrome users in December"
"Desktop visitors from Europe"

Data Management

Data Retention:

Cloud:

Check your plan's retention policy
Typically 12 months or unlimited

Self-Hosted:

Configure in database
Automated archival scripts
Manual data cleanup

Data Export:

Export analytics data:

Select date range
Click "Export" button
Download CSV
Import into Excel, Google Sheets, or BI tools

API Access:

Use Umami API for programmatic access:

// Get website stats
const response = await fetch('https://analytics.example.com/api/websites/abc123/stats', {
  headers: {
    'Authorization': `Bearer ${apiToken}`
  }
});

const stats = await response.json();

Troubleshooting

Script Not Loading:

Verify script URL is correct
Check for ad blockers
Inspect browser console for errors
Ensure website ID is correct

No Data Appearing:

Confirm script is on every page
Check website ID matches dashboard
Verify no JavaScript errors on page
Test in incognito mode (ad blockers disabled)

Events Not Tracking:

Ensure window.umami exists before calling track()
Check event name for typos
Verify events appear in browser Network tab
Look for events in dashboard (may take a few seconds)

Performance Issues:

Umami script is very lightweight (< 2KB)
Use async attribute on script tag
Self-hosted? Check server performance

Privacy and Compliance

GDPR Compliance:

Umami doesn't collect personal data
No cookie consent required
Visitors can't be identified individually
Data is anonymous by design

Privacy Policy:

Example privacy policy language:

We use Umami Analytics to understand how visitors use our website. Umami:
- Does not use cookies
- Does not collect personal information
- Does not track you across websites
- Respects your privacy with anonymous, aggregated analytics

For more information, visit: https://umami.is/privacy

Data Subject Rights:

No personal data = no GDPR data subject requests
No individual user data to delete
No data portability requirements (data is anonymous)

Migration from Other Platforms

From Google Analytics:

What changes:

No user IDs or client IDs
No demographic data
No interest categories
Simpler, cleaner metrics
Privacy-first approach

What stays:

Pageviews
Traffic sources
Geographic data (country-level)
Device/browser/OS data
Custom event tracking

Parallel Tracking:

Run both during transition:

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>

<!-- Umami -->
<script async src="https://analytics.example.com/script.js" data-website-id="abc123"></script>

Compare data for 1-2 weeks, then remove Google Analytics when confident.

Implementation Guides

Detailed setup instructions for specific scenarios:

Install or Embed the Tag or SDK - Installation methods for all platforms
Event Tracking - Track custom user interactions
Data Layer Setup - Configure event metadata
Cross-Domain Tracking - Track multiple domains
Server-Side vs Client-Side - Choose tracking approach

Best Practices

Install Early: Add Umami script before launch to establish baseline
Use Custom Events: Track important user actions beyond pageviews
Review Regularly: Check dashboard weekly for insights
Respect Privacy: Umami is privacy-friendly, but avoid tracking sensitive actions
Document Setup: Keep track of website IDs and configurations
Test Thoroughly: Verify tracking before deploying to production
Self-Host When Possible: Maximum privacy and data ownership
Export Data Periodically: Keep backups of important metrics

Success Metrics

Your Umami implementation is successful when:

✓ Script loads on all pages without errors ✓ Pageviews appear in dashboard within seconds ✓ Custom events track correctly ✓ Team has access to dashboard ✓ Data updates in real-time ✓ No user privacy concerns ✓ Minimal performance impact ✓ Stakeholders can view reports

Getting Help

Resources:

Common Questions:

Check GitHub Discussions for solutions
Search existing issues on GitHub
Ask in Discord community
Review official documentation

Next Steps

Once Umami is installed and tracking:

Set Up Custom Events: Identify and track key user actions
Create Dashboards: Build views for different stakeholders
Establish Baselines: Understand typical traffic patterns
Monitor Trends: Watch for changes in key metrics
Share Insights: Distribute reports to team members
Refine Tracking: Add more events as you identify needs
Explore API: Build custom integrations and reports

Umami's simplicity is its strength - you get essential analytics without the complexity, cost, and privacy concerns of traditional platforms.

शीर्ष पर वापस जाएँ