# Umami — Modern Privacy-Focused Website Analytics

> Umami is an open-source, privacy-focused analytics platform and Google Analytics alternative with real-time dashboards, event tracking, and multi-site support.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
git clone https://github.com/umami-software/umami.git
cd umami
cp .env.example .env
# Set DATABASE_URL in .env
npm install
npx prisma migrate deploy
npm run build
npm start
```

Open `http://localhost:3000` — login with admin/umami and add your first website.

## Intro

**Umami** is an open-source, privacy-focused web analytics platform that serves as a modern alternative to Google Analytics, Mixpanel, and Amplitude. Built with Next.js and supporting both PostgreSQL and MySQL, it provides beautiful real-time dashboards, custom event tracking, and product analytics features — all without cookies and fully GDPR compliant.

With 36K+ GitHub stars and MIT license, Umami is one of the most popular open-source analytics solutions, trusted by thousands of websites worldwide for its simplicity, performance, and respect for user privacy.

## What Umami Does

Umami provides comprehensive analytics across web and product metrics:

- **Real-time Dashboard**: Live visitor count, page views, sessions, and geographic distribution
- **Page Analytics**: Detailed per-page metrics with entry/exit tracking and flow visualization
- **Custom Events**: Track button clicks, form submissions, signups, purchases, and any user interaction
- **User Journey**: Session replay, funnel analysis, and conversion path tracking
- **Audience Segmentation**: Filter by country, device, browser, OS, referrer, and custom properties
- **UTM Tracking**: Campaign attribution with source, medium, campaign, term, and content parameters
- **Multi-site**: Manage unlimited websites from a single dashboard with team sharing

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your Site   │────▶│  Umami       │────▶│  PostgreSQL  │
│  (Tracker)   │     │  (Next.js)   │     │  or MySQL    │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────┴───────┐
                     │  Dashboard   │
                     │  (React UI)  │
                     └──────────────┘
```

## Installation

### Docker Compose (Recommended)

```yaml
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: your-random-secret
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  umami-db:
```

```bash
docker compose up -d
# Login: admin / umami
```

### One-Click Deploy

Umami supports one-click deployment to:
- **Vercel**: Connect GitHub repo → auto-deploy with PostgreSQL (Neon/Supabase)
- **Railway**: Template-based deploy with built-in PostgreSQL
- **DigitalOcean**: App Platform with managed database

## Tracking Setup

### Basic Page Tracking

```html
<script defer src="https://analytics.yourdomain.com/script.js"
  data-website-id="your-website-id"></script>
```

The tracking script is only 2KB gzipped and loads asynchronously — zero impact on page performance.

### Custom Event Tracking

```javascript
// Track button click
umami.track('signup-click', { plan: 'pro', source: 'landing' });

// Track form submission
umami.track('contact-form', {
  type: 'enterprise',
  company: 'Acme Corp'
});

// Track page view with custom data
umami.track({ url: '/virtual-page', title: 'Custom Page' });
```

### React/Next.js Integration

```tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          defer
          src="https://analytics.yourdomain.com/script.js"
          data-website-id="your-website-id"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

## API & Integrations

### REST API

```bash
# Authenticate
TOKEN=$(curl -s -X POST https://analytics.yourdomain.com/api/auth/login 
  -H "Content-Type: application/json" 
  -d '{"username":"admin","password":"umami"}' | jq -r '.token')

# Get website stats
curl "https://analytics.yourdomain.com/api/websites/{id}/stats?startAt=1704067200000&endAt=1706745600000" 
  -H "Authorization: Bearer $TOKEN"

# Get page views
curl "https://analytics.yourdomain.com/api/websites/{id}/pageviews?startAt=1704067200000&endAt=1706745600000&unit=day" 
  -H "Authorization: Bearer $TOKEN"
```

### Umami vs Plausible

| Feature | Umami | Plausible |
|---------|-------|-----------|
| License | MIT | AGPL-3.0 |
| Stack | Next.js + PostgreSQL | Elixir + ClickHouse |
| Custom events | Rich props | Basic props |
| User journey | Funnels + paths | Goals only |
| Product analytics | Yes (cohorts, segments) | Basic |
| Team management | Yes | Yes |
| API | Full REST API | Stats API |
| Script size | 2KB | <1KB |

## FAQ

**Q: Umami or Plausible?**
A: If you only need clean traffic stats, Plausible is lighter. If you need product analytics features (user segmentation, funnel analysis, user journeys), Umami is more comprehensive. Umami's MIT license is also more permissive.

**Q: PostgreSQL or MySQL?**
A: PostgreSQL is recommended. Both are supported, but Umami's core development targets PostgreSQL, with better community support and documentation.

**Q: Can it handle high-traffic sites?**
A: Yes. Umami uses efficient aggregation queries — a single instance can handle millions of daily page views. For very large sites, scale horizontally with multiple Umami instances and database read replicas.

## Source & Thanks

- GitHub: [umami-software/umami](https://github.com/umami-software/umami) — 36K+ ⭐ | MIT
- Website: [umami.is](https://umami.is)

---
Source: https://tokrepo.com/en/workflows/umami-modern-privacy-focused-website-analytics-55eb661a
Author: AI Open Source