Projects/kompose/docs/content/5.stacks/track.md

---
title: Track - Privacy-First Analytics HQ
description: "We count visitors, not cookies!"
navigation:
  icon: i-lucide-bar-chart
---

> *"We count visitors, not cookies!"* - Umami Analytics

## What's This All About?

Umami is your self-hosted, privacy-focused alternative to Google Analytics! It's like having all the insights without selling your soul (or your visitors' data) to Big Tech. Track what matters, respect privacy, stay GDPR compliant, and sleep well at night knowing you're not contributing to the surveillance economy! :icon{name="lucide:search"}

## The Analytics Ace

### :icon{name="lucide:trending-up"} Umami

**Container**: `track_app`  
**Image**: `ghcr.io/umami-software/umami:postgresql-latest`  
**Port**: 3000  
**Home**: https://umami.pivoine.art

Umami is analytics done right:
- :icon{name="lucide:lock"} **Privacy-First**: No cookies, no tracking pixels, no creepy stuff
- 🇪🇺 **GDPR Compliant**: By design, not as an afterthought
- :icon{name="lucide:bar-chart"} **Beautiful Dashboards**: Real-time, clean, insightful
- 🌍 **Multi-Site**: Track unlimited websites
- :icon{name="lucide:users"} **Team Features**: Invite team members
- 📱 **Events Tracking**: Custom events and goals
- :icon{name="lucide:palette"} **Simple Script**: Just one line of JavaScript
- 🆓 **Open Source**: Free forever, your data, your server

## Features That Make Sense :icon{name="lucide:sparkles"}

### Core Metrics
- :icon{name="lucide:trending-up"} **Page Views**: Real-time visitor counts
- :icon{name="lucide:user"} **Unique Visitors**: Who's new, who's returning
- :icon{name="lucide:globe"} **Referrers**: Where traffic comes from
- 📱 **Devices**: Desktop vs Mobile vs Tablet
- 🌍 **Countries**: Geographic distribution
- :icon{name="lucide:monitor"} **Browsers**: Chrome, Firefox, Safari, etc.
- :icon{name="lucide:laptop"} **Operating Systems**: Windows, Mac, Linux, etc.
- :icon{name="lucide:file"} **Pages**: Most popular content

### Advanced Features
- :icon{name="lucide:target"} **Custom Events**: Track buttons, forms, videos
- ⏱️ **Time on Site**: Engagement metrics
- :icon{name="lucide:bar-chart"} **Real-time Data**: Live visitor updates
- 📅 **Date Ranges**: Custom time periods
- :icon{name="lucide:search"} **Filters**: Drill down into data
- 📤 **Export Data**: CSV downloads
- :icon{name="lucide:link"} **Share Links**: Public dashboard links
- :icon{name="lucide:palette"} **Themes**: Light/Dark mode

## Configuration Breakdown

### Database Connection
```bash
DATABASE_URL=postgresql://user:password@postgres:5432/umami
DATABASE_TYPE=postgresql
```

Stores all analytics data in PostgreSQL - reliable, scalable, queryable!

### App Secret
```bash
APP_SECRET=your-random-secret-here
```
Used for hashing and security. Generate with:
```bash
openssl rand -hex 32
```

### Health Check
Every 30 seconds, Umami pings itself:
```bash
curl -f http://localhost:3000/api/heartbeat
```

## First Time Setup :icon{name="lucide:rocket"}

### 1. Create Database
```bash
docker exec data_postgres createdb -U your_db_user umami
```

### 2. Start the Stack
```bash
docker compose up -d
```

### 3. First Login
```
URL: https://umami.pivoine.art
Username: admin
Password: umami
```

**:icon{name="lucide:siren"} IMMEDIATELY CHANGE THE PASSWORD!**
1. Click on username → Profile
2. Change password
3. Breathe easy

### 4. Add Your First Website

1. **Settings → Websites → Add Website**
2. **Name**: "My Awesome Blog"
3. **Domain**: "myblog.com"
4. **Enable Share URL**: Optional
5. **Save**

### 5. Get Your Tracking Code

After adding website, click "Edit" → "Tracking Code":
```html
<script async defer 
  data-website-id="your-unique-id"
  src="https://umami.pivoine.art/script.js">
</script>
```

### 6. Add to Your Website

Place in `<head>` section:
```html
<!DOCTYPE html>
<html>
<head>
  <title>My Site</title>
  <!-- Umami Analytics -->
  <script async defer 
    data-website-id="abc123..."
    src="https://umami.pivoine.art/script.js">
  </script>
</head>
<body>
  <!-- content -->
</body>
</html>
```

## Tracking Events :icon{name="lucide:target"}

### Automatic Tracking
Page views are tracked automatically. That's it! :icon{name="lucide:party-popper"}

### Custom Events

**Track Button Clicks**:
```html
<button class="umami--click--signup-button">
  Sign Up
</button>
```

**Track Form Submissions**:
```html
<form class="umami--click--contact-form">
  <!-- form fields -->
</form>
```

**Using JavaScript**:
```javascript
// Track custom event
umami.track('Newsletter Signup', {
  email: 'user@example.com',
  source: 'homepage'
});

// Track with properties
umami.track(props => ({
  ...props,
  category: 'ecommerce',
  action: 'purchase',
  value: 99.99
}));
```

### Event Examples

**E-commerce**:
```javascript
// Product view
umami.track('Product View', { 
  product_id: '123',
  product_name: 'Cool Widget'
});

// Add to cart
umami.track('Add to Cart', {
  product_id: '123',
  quantity: 1
});

// Purchase
umami.track('Purchase', {
  order_id: 'ORDER-123',
  total: 99.99
});
```

**Content Engagement**:
```javascript
// Video play
umami.track('Video Play', {
  video_id: 'intro-video',
  duration: 120
});

// Download
umami.track('File Download', {
  filename: 'guide.pdf'
});
```

**User Actions**:
```javascript
// Search
umami.track('Search', {
  query: 'best practices'
});

// Share
umami.track('Social Share', {
  platform: 'twitter',
  url: window.location.href
});
```

## Dashboard Features :icon{name="lucide:bar-chart"}

### Overview
- 👁️ Real-time visitor count
- :icon{name="lucide:trending-up"} Views & visitors today
- 🕐 Average time on site
- :icon{name="lucide:refresh-cw"} Bounce rate

### Realtime View
Watch visitors as they browse:
- Current pages being viewed
- Referrer sources
- Countries
- Live count

### Reports
- 📅 Custom date ranges
- :icon{name="lucide:bar-chart"} Page comparisons
- 🌍 Geographic heatmaps
- 📱 Device breakdowns
- :icon{name="lucide:search"} Referrer analysis

### Filters
Drill down with:
- Date range
- Country
- Device type
- Browser
- OS
- URL path

## Multi-Website Management :icon{name="lucide:globe"}

### Add Multiple Sites
```
Settings → Websites → Add Website
```

Track unlimited sites from one Umami instance!

### Team Access
```
Settings → Teams → Add Team Member
```

Invite colleagues with different permission levels:
- **Owner**: Full access
- **User**: View only
- **View Only**: Stats but no config changes

### Shared Reports
Generate public dashboard links:
```
Website → Share → Enable & Copy URL
```

Anyone with the link can view stats (no login needed)!

## Privacy Features :icon{name="lucide:lock"}

### What Umami Does NOT Track
- ❌ Personal information
- ❌ Cookies (beyond session)
- ❌ IP addresses (optional hashing)
- ❌ Cross-site tracking
- ❌ Fingerprinting

### What Umami DOES Track
- ✅ Page views (anonymized)
- ✅ Referrers
- ✅ Device types (generic)
- ✅ Countries (city-level optional)
- ✅ Custom events

### GDPR Compliance
Umami is GDPR-compliant by default:
- No consent banner needed (in most cases)
- Data stored on YOUR server
- Easy data export/deletion
- No third-party data sharing
- Anonymous by design

## Ports & Networking

- **Internal Port**: 3000
- **External Access**: Via Traefik at https://umami.pivoine.art
- **Network**: `kompose` (database access)
- **Database**: PostgreSQL (from data stack)

## API Access :icon{name="lucide:plug"}

Umami has a REST API for programmatic access!

### Authentication
```bash
curl -X POST https://umami.pivoine.art/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'
```

Returns JWT token for API requests.

### Get Website Stats
```bash
curl https://umami.pivoine.art/api/websites/YOUR-WEBSITE-ID/stats \
  -H "Authorization: Bearer YOUR-JWT-TOKEN" \
  -d "startAt=1609459200000&endAt=1612137600000"
```

### Track Event via API
```bash
curl -X POST https://umami.pivoine.art/api/send \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "website": "your-website-id",
      "url": "/page",
      "event_name": "custom-event"
    },
    "type": "event"
  }'
```

## Performance & Scaling :icon{name="lucide:trending-up"}

### For Small Sites (<10k/month)
Default setup works great! No optimization needed.

### For Medium Sites (10k-100k/month)
- ✅ Enable database indexes (auto-created)
- ✅ Regular database maintenance
- ✅ Monitor disk space

### For Large Sites (100k+/month)
- :icon{name="lucide:rocket"} Increase PostgreSQL memory
- :icon{name="lucide:rocket"} Add read replicas
- :icon{name="lucide:rocket"} Consider CDN for script.js
- :icon{name="lucide:rocket"} Enable database connection pooling

### Optimization Tips
```sql
-- Regular vacuum (PostgreSQL)
VACUUM ANALYZE;

-- Check index usage
SELECT * FROM pg_stat_user_indexes;
```

## Data Management :icon{name="lucide:database"}

### Export Data
```
Settings → Export → Select Date Range → Download CSV
```

### Database Backups
```bash
# Backup Umami database
docker exec data_postgres pg_dump -U your_db_user umami > umami-backup.sql

# Restore if needed
docker exec -i data_postgres psql -U your_db_user umami < umami-backup.sql
```

### Data Retention
Configure automatic cleanup:
```sql
-- Delete data older than 1 year
DELETE FROM event 
WHERE created_at < NOW() - INTERVAL '1 year';
```

## Troubleshooting :icon{name="lucide:wrench"}

**Q: Script not loading?**  
A: Check browser console for errors, verify script URL is correct

**Q: No data showing up?**  
A: Verify tracking code is on page, check browser ad blockers

**Q: "Website not found" error?**  
A: Check website ID matches, ensure website is active

**Q: Slow dashboard?**  
A: Reduce date range, check database performance, add indexes

**Q: Can't log in?**  
A: Reset password via database or recreate user

## Integration Examples

### Hugo (Static Site Generator)
```html
<!-- layouts/partials/umami.html -->
{{ if not .Site.IsServer }}
<script async defer 
  data-website-id="{{ .Site.Params.umamiId }}"
  src="{{ .Site.Params.umamiUrl }}/script.js">
</script>
{{ end }}
```

### Next.js
```javascript
// components/Analytics.js
import Script from 'next/script'

export default function Analytics() {
  return (
    <Script
      async
      defer
      data-website-id={process.env.NEXT_PUBLIC_UMAMI_ID}
      src="https://umami.pivoine.art/script.js"
    />
  )
}
```

### WordPress
Install via plugin or add to theme's `header.php`:
```php
<?php if (!is_user_logged_in()) { ?>
<script async defer 
  data-website-id="your-id"
  src="https://umami.pivoine.art/script.js">
</script>
<?php } ?>
```

## Umami vs. Google Analytics

| Feature | Umami | Google Analytics |
|---------|-------|------------------|
| Privacy | ✅ Excellent | ❌ Terrible |
| GDPR | ✅ Compliant | :icon{name="lucide:alert-triangle"} Complicated |
| Data Ownership | ✅ Yours | ❌ Google's |
| Cookie Banner | ✅ Not needed | ❌ Required |
| Speed | ✅ Fast | :icon{name="lucide:alert-triangle"} Slower |
| Setup | ✅ Simple | :icon{name="lucide:alert-triangle"} Complex |
| Cost | ✅ Free | ✅ Free (but...) |
| Learning Curve | ✅ Easy | ❌ Steep |

## Why Track with Umami? :icon{name="lucide:target"}

- :icon{name="lucide:lock"} **Privacy**: Respect your visitors
- :icon{name="lucide:bar-chart"} **Insights**: Get data that matters
- :icon{name="lucide:palette"} **Simple**: No complexity overload
- 🆓 **Free**: No limits, no upsells
- :icon{name="lucide:rocket"} **Fast**: Lightweight script
- :icon{name="lucide:dumbbell"} **Reliable**: Self-hosted stability
- 🌍 **Ethical**: Do the right thing

## Advanced Features

### Custom Domains
Point your own domain to Umami:
```
analytics.yourdomain.com → Traefik → Umami
```

### Visitor Segments
Filter by any combination:
- Country + Device
- Referrer + Browser
- Page + OS
- Custom event properties

### Goals & Funnels
Track conversion paths:
1. Landing page view
2. Feature page view
3. Signup form
4. Thank you page

## Resources

- [Umami Documentation](https://umami.is/docs)
- [API Reference](https://umami.is/docs/api)
- [GitHub Repository](https://github.com/umami-software/umami)
- [Community Forum](https://github.com/umami-software/umami/discussions)

---

*"The best analytics are the ones that respect privacy while still giving you the insights you need."* - Ethical Analytics Manifesto :icon{name="lucide:bar-chart"}:icon{name="lucide:sparkles"}
feat: AR 2025-10-08 17:56:29 +02:00			`---`
feat: doocs 2025-10-09 00:30:31 +02:00			`title: Track - Privacy-First Analytics HQ`
feat: AR 2025-10-08 17:56:29 +02:00			`description: "We count visitors, not cookies!"`
feat: doocs 2025-10-09 00:30:31 +02:00			`navigation:`
			`icon: i-lucide-bar-chart`
feat: AR 2025-10-08 17:56:29 +02:00			`---`

A new start 2025-10-08 10:35:48 +02:00			`> "We count visitors, not cookies!" - Umami Analytics`

			`## What's This All About?`

feat: doocs 2025-10-09 00:30:31 +02:00			`Umami is your self-hosted, privacy-focused alternative to Google Analytics! It's like having all the insights without selling your soul (or your visitors' data) to Big Tech. Track what matters, respect privacy, stay GDPR compliant, and sleep well at night knowing you're not contributing to the surveillance economy! :icon{name="lucide:search"}`
A new start 2025-10-08 10:35:48 +02:00
			`## The Analytics Ace`

feat: doocs 2025-10-09 00:30:31 +02:00			`### :icon{name="lucide:trending-up"} Umami`
A new start 2025-10-08 10:35:48 +02:00
			Container: `track_app`
			Image: `ghcr.io/umami-software/umami:postgresql-latest`
			`Port: 3000`
			`Home: https://umami.pivoine.art`

			`Umami is analytics done right:`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:lock"} Privacy-First: No cookies, no tracking pixels, no creepy stuff`
A new start 2025-10-08 10:35:48 +02:00			`- 🇪🇺 GDPR Compliant: By design, not as an afterthought`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:bar-chart"} Beautiful Dashboards: Real-time, clean, insightful`
A new start 2025-10-08 10:35:48 +02:00			`- 🌍 Multi-Site: Track unlimited websites`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:users"} Team Features: Invite team members`
A new start 2025-10-08 10:35:48 +02:00			`- 📱 Events Tracking: Custom events and goals`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:palette"} Simple Script: Just one line of JavaScript`
A new start 2025-10-08 10:35:48 +02:00			`- 🆓 Open Source: Free forever, your data, your server`

feat: doocs 2025-10-09 00:30:31 +02:00			`## Features That Make Sense :icon{name="lucide:sparkles"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Core Metrics`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:trending-up"} Page Views: Real-time visitor counts`
			`- :icon{name="lucide:user"} Unique Visitors: Who's new, who's returning`
			`- :icon{name="lucide:globe"} Referrers: Where traffic comes from`
A new start 2025-10-08 10:35:48 +02:00			`- 📱 Devices: Desktop vs Mobile vs Tablet`
			`- 🌍 Countries: Geographic distribution`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:monitor"} Browsers: Chrome, Firefox, Safari, etc.`
			`- :icon{name="lucide:laptop"} Operating Systems: Windows, Mac, Linux, etc.`
			`- :icon{name="lucide:file"} Pages: Most popular content`
A new start 2025-10-08 10:35:48 +02:00
			`### Advanced Features`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:target"} Custom Events: Track buttons, forms, videos`
A new start 2025-10-08 10:35:48 +02:00			`- ⏱️ Time on Site: Engagement metrics`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:bar-chart"} Real-time Data: Live visitor updates`
A new start 2025-10-08 10:35:48 +02:00			`- 📅 Date Ranges: Custom time periods`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:search"} Filters: Drill down into data`
A new start 2025-10-08 10:35:48 +02:00			`- 📤 Export Data: CSV downloads`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:link"} Share Links: Public dashboard links`
			`- :icon{name="lucide:palette"} Themes: Light/Dark mode`
A new start 2025-10-08 10:35:48 +02:00
			`## Configuration Breakdown`

			`### Database Connection`
			```bash
			`DATABASE_URL=postgresql://user:password@postgres:5432/umami`
			`DATABASE_TYPE=postgresql`
			```

			`Stores all analytics data in PostgreSQL - reliable, scalable, queryable!`

			`### App Secret`
			```bash
			`APP_SECRET=your-random-secret-here`
			```
			`Used for hashing and security. Generate with:`
			```bash
			`openssl rand -hex 32`
			```

			`### Health Check`
			`Every 30 seconds, Umami pings itself:`
			```bash
			`curl -f http://localhost:3000/api/heartbeat`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## First Time Setup :icon{name="lucide:rocket"}`
A new start 2025-10-08 10:35:48 +02:00
			`### 1. Create Database`
			```bash
			`docker exec data_postgres createdb -U your_db_user umami`
			```

			`### 2. Start the Stack`
			```bash
			`docker compose up -d`
			```

			`### 3. First Login`
			```
			`URL: https://umami.pivoine.art`
			`Username: admin`
			`Password: umami`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`:icon{name="lucide:siren"} IMMEDIATELY CHANGE THE PASSWORD!`
A new start 2025-10-08 10:35:48 +02:00			`1. Click on username → Profile`
			`2. Change password`
			`3. Breathe easy`

			`### 4. Add Your First Website`

			`1. Settings → Websites → Add Website`
			`2. Name: "My Awesome Blog"`
			`3. Domain: "myblog.com"`
			`4. Enable Share URL: Optional`
			`5. Save`

			`### 5. Get Your Tracking Code`

			`After adding website, click "Edit" → "Tracking Code":`
			```html
			`<script async defer`
			`data-website-id="your-unique-id"`
			`src="https://umami.pivoine.art/script.js">`
			`</script>`
			```

			`### 6. Add to Your Website`

			Place in `<head>` section:
			```html
			`<!DOCTYPE html>`
			`<html>`
			`<head>`
			`<title>My Site</title>`
			`<!-- Umami Analytics -->`
			`<script async defer`
			`data-website-id="abc123..."`
			`src="https://umami.pivoine.art/script.js">`
			`</script>`
			`</head>`
			`<body>`
feat: doocs 2025-10-09 00:30:31 +02:00			`<!-- content -->`
A new start 2025-10-08 10:35:48 +02:00			`</body>`
			`</html>`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## Tracking Events :icon{name="lucide:target"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Automatic Tracking`
feat: doocs 2025-10-09 00:30:31 +02:00			`Page views are tracked automatically. That's it! :icon{name="lucide:party-popper"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Custom Events`

			`Track Button Clicks:`
			```html
			`<button class="umami--click--signup-button">`
			`Sign Up`
			`</button>`
			```

			`Track Form Submissions:`
			```html
			`<form class="umami--click--contact-form">`
			`<!-- form fields -->`
			`</form>`
			```

			`Using JavaScript:`
			```javascript
			`// Track custom event`
			`umami.track('Newsletter Signup', {`
			`email: 'user@example.com',`
			`source: 'homepage'`
			`});`

			`// Track with properties`
			`umami.track(props => ({`
			`...props,`
			`category: 'ecommerce',`
			`action: 'purchase',`
			`value: 99.99`
			`}));`
			```

			`### Event Examples`

			`E-commerce:`
			```javascript
			`// Product view`
			`umami.track('Product View', {`
			`product_id: '123',`
			`product_name: 'Cool Widget'`
			`});`

			`// Add to cart`
			`umami.track('Add to Cart', {`
			`product_id: '123',`
			`quantity: 1`
			`});`

			`// Purchase`
			`umami.track('Purchase', {`
			`order_id: 'ORDER-123',`
			`total: 99.99`
			`});`
			```

			`Content Engagement:`
			```javascript
			`// Video play`
			`umami.track('Video Play', {`
			`video_id: 'intro-video',`
			`duration: 120`
			`});`

			`// Download`
			`umami.track('File Download', {`
			`filename: 'guide.pdf'`
			`});`
			```

			`User Actions:`
			```javascript
			`// Search`
			`umami.track('Search', {`
			`query: 'best practices'`
			`});`

			`// Share`
			`umami.track('Social Share', {`
			`platform: 'twitter',`
			`url: window.location.href`
			`});`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## Dashboard Features :icon{name="lucide:bar-chart"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Overview`
			`- 👁️ Real-time visitor count`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:trending-up"} Views & visitors today`
A new start 2025-10-08 10:35:48 +02:00			`- 🕐 Average time on site`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:refresh-cw"} Bounce rate`
A new start 2025-10-08 10:35:48 +02:00
			`### Realtime View`
			`Watch visitors as they browse:`
			`- Current pages being viewed`
			`- Referrer sources`
			`- Countries`
			`- Live count`

			`### Reports`
			`- 📅 Custom date ranges`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:bar-chart"} Page comparisons`
A new start 2025-10-08 10:35:48 +02:00			`- 🌍 Geographic heatmaps`
			`- 📱 Device breakdowns`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:search"} Referrer analysis`
A new start 2025-10-08 10:35:48 +02:00
			`### Filters`
			`Drill down with:`
			`- Date range`
			`- Country`
			`- Device type`
			`- Browser`
			`- OS`
			`- URL path`

feat: doocs 2025-10-09 00:30:31 +02:00			`## Multi-Website Management :icon{name="lucide:globe"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Add Multiple Sites`
			```
			`Settings → Websites → Add Website`
			```

			`Track unlimited sites from one Umami instance!`

			`### Team Access`
			```
			`Settings → Teams → Add Team Member`
			```

			`Invite colleagues with different permission levels:`
			`- Owner: Full access`
			`- User: View only`
			`- View Only: Stats but no config changes`

			`### Shared Reports`
			`Generate public dashboard links:`
			```
			`Website → Share → Enable & Copy URL`
			```

			`Anyone with the link can view stats (no login needed)!`

feat: doocs 2025-10-09 00:30:31 +02:00			`## Privacy Features :icon{name="lucide:lock"}`
A new start 2025-10-08 10:35:48 +02:00
			`### What Umami Does NOT Track`
			`- ❌ Personal information`
			`- ❌ Cookies (beyond session)`
			`- ❌ IP addresses (optional hashing)`
			`- ❌ Cross-site tracking`
			`- ❌ Fingerprinting`

			`### What Umami DOES Track`
			`- ✅ Page views (anonymized)`
			`- ✅ Referrers`
			`- ✅ Device types (generic)`
			`- ✅ Countries (city-level optional)`
			`- ✅ Custom events`

			`### GDPR Compliance`
			`Umami is GDPR-compliant by default:`
			`- No consent banner needed (in most cases)`
			`- Data stored on YOUR server`
			`- Easy data export/deletion`
			`- No third-party data sharing`
			`- Anonymous by design`

			`## Ports & Networking`

			`- Internal Port: 3000`
			`- External Access: Via Traefik at https://umami.pivoine.art`
			- Network: `kompose` (database access)
			`- Database: PostgreSQL (from data stack)`

feat: doocs 2025-10-09 00:30:31 +02:00			`## API Access :icon{name="lucide:plug"}`
A new start 2025-10-08 10:35:48 +02:00
			`Umami has a REST API for programmatic access!`

			`### Authentication`
			```bash
			`curl -X POST https://umami.pivoine.art/api/auth/login \`
			`-H "Content-Type: application/json" \`
			`-d '{"username":"admin","password":"your-password"}'`
			```

			`Returns JWT token for API requests.`

			`### Get Website Stats`
			```bash
			`curl https://umami.pivoine.art/api/websites/YOUR-WEBSITE-ID/stats \`
			`-H "Authorization: Bearer YOUR-JWT-TOKEN" \`
			`-d "startAt=1609459200000&endAt=1612137600000"`
			```

			`### Track Event via API`
			```bash
			`curl -X POST https://umami.pivoine.art/api/send \`
			`-H "Content-Type: application/json" \`
			`-d '{`
			`"payload": {`
			`"website": "your-website-id",`
			`"url": "/page",`
			`"event_name": "custom-event"`
			`},`
			`"type": "event"`
			`}'`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## Performance & Scaling :icon{name="lucide:trending-up"}`
A new start 2025-10-08 10:35:48 +02:00
			`### For Small Sites (<10k/month)`
			`Default setup works great! No optimization needed.`

			`### For Medium Sites (10k-100k/month)`
			`- ✅ Enable database indexes (auto-created)`
			`- ✅ Regular database maintenance`
			`- ✅ Monitor disk space`

			`### For Large Sites (100k+/month)`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:rocket"} Increase PostgreSQL memory`
			`- :icon{name="lucide:rocket"} Add read replicas`
			`- :icon{name="lucide:rocket"} Consider CDN for script.js`
			`- :icon{name="lucide:rocket"} Enable database connection pooling`
A new start 2025-10-08 10:35:48 +02:00
			`### Optimization Tips`
			```sql
			`-- Regular vacuum (PostgreSQL)`
			`VACUUM ANALYZE;`

			`-- Check index usage`
			`SELECT * FROM pg_stat_user_indexes;`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## Data Management :icon{name="lucide:database"}`
A new start 2025-10-08 10:35:48 +02:00
			`### Export Data`
			```
			`Settings → Export → Select Date Range → Download CSV`
			```

			`### Database Backups`
			```bash
			`# Backup Umami database`
			`docker exec data_postgres pg_dump -U your_db_user umami > umami-backup.sql`

			`# Restore if needed`
			`docker exec -i data_postgres psql -U your_db_user umami < umami-backup.sql`
			```

			`### Data Retention`
			`Configure automatic cleanup:`
			```sql
			`-- Delete data older than 1 year`
			`DELETE FROM event`
			`WHERE created_at < NOW() - INTERVAL '1 year';`
			```

feat: doocs 2025-10-09 00:30:31 +02:00			`## Troubleshooting :icon{name="lucide:wrench"}`
A new start 2025-10-08 10:35:48 +02:00
			`Q: Script not loading?`
			`A: Check browser console for errors, verify script URL is correct`

			`Q: No data showing up?`
			`A: Verify tracking code is on page, check browser ad blockers`

			`Q: "Website not found" error?`
			`A: Check website ID matches, ensure website is active`

			`Q: Slow dashboard?`
			`A: Reduce date range, check database performance, add indexes`

			`Q: Can't log in?`
			`A: Reset password via database or recreate user`

			`## Integration Examples`

			`### Hugo (Static Site Generator)`
			```html
			`<!-- layouts/partials/umami.html -->`
			`{{ if not .Site.IsServer }}`
			`<script async defer`
			`data-website-id="{{ .Site.Params.umamiId }}"`
			`src="{{ .Site.Params.umamiUrl }}/script.js">`
			`</script>`
			`{{ end }}`
			```

			`### Next.js`
			```javascript
			`// components/Analytics.js`
			`import Script from 'next/script'`

			`export default function Analytics() {`
			`return (`
			`<Script`
			`async`
			`defer`
			`data-website-id={process.env.NEXT_PUBLIC_UMAMI_ID}`
			`src="https://umami.pivoine.art/script.js"`
			`/>`
			`)`
			`}`
			```

			`### WordPress`
			Install via plugin or add to theme's `header.php`:
			```php
			`<?php if (!is_user_logged_in()) { ?>`
			`<script async defer`
			`data-website-id="your-id"`
			`src="https://umami.pivoine.art/script.js">`
			`</script>`
			`<?php } ?>`
			```

			`## Umami vs. Google Analytics`

			`\| Feature \| Umami \| Google Analytics \|`
			`\|---------\|-------\|------------------\|`
			`\| Privacy \| ✅ Excellent \| ❌ Terrible \|`
feat: doocs 2025-10-09 00:30:31 +02:00			`\| GDPR \| ✅ Compliant \| :icon{name="lucide:alert-triangle"} Complicated \|`
A new start 2025-10-08 10:35:48 +02:00			`\| Data Ownership \| ✅ Yours \| ❌ Google's \|`
			`\| Cookie Banner \| ✅ Not needed \| ❌ Required \|`
feat: doocs 2025-10-09 00:30:31 +02:00			`\| Speed \| ✅ Fast \| :icon{name="lucide:alert-triangle"} Slower \|`
			`\| Setup \| ✅ Simple \| :icon{name="lucide:alert-triangle"} Complex \|`
A new start 2025-10-08 10:35:48 +02:00			`\| Cost \| ✅ Free \| ✅ Free (but...) \|`
			`\| Learning Curve \| ✅ Easy \| ❌ Steep \|`

feat: doocs 2025-10-09 00:30:31 +02:00			`## Why Track with Umami? :icon{name="lucide:target"}`
A new start 2025-10-08 10:35:48 +02:00
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:lock"} Privacy: Respect your visitors`
			`- :icon{name="lucide:bar-chart"} Insights: Get data that matters`
			`- :icon{name="lucide:palette"} Simple: No complexity overload`
A new start 2025-10-08 10:35:48 +02:00			`- 🆓 Free: No limits, no upsells`
feat: doocs 2025-10-09 00:30:31 +02:00			`- :icon{name="lucide:rocket"} Fast: Lightweight script`
			`- :icon{name="lucide:dumbbell"} Reliable: Self-hosted stability`
A new start 2025-10-08 10:35:48 +02:00			`- 🌍 Ethical: Do the right thing`

			`## Advanced Features`

			`### Custom Domains`
			`Point your own domain to Umami:`
			```
			`analytics.yourdomain.com → Traefik → Umami`
			```

			`### Visitor Segments`
			`Filter by any combination:`
			`- Country + Device`
			`- Referrer + Browser`
			`- Page + OS`
			`- Custom event properties`

			`### Goals & Funnels`
			`Track conversion paths:`
			`1. Landing page view`
			`2. Feature page view`
			`3. Signup form`
			`4. Thank you page`

			`## Resources`

			`- [Umami Documentation](https://umami.is/docs)`
			`- [API Reference](https://umami.is/docs/api)`
			`- [GitHub Repository](https://github.com/umami-software/umami)`
			`- [Community Forum](https://github.com/umami-software/umami/discussions)`

			`---`

feat: doocs 2025-10-09 00:30:31 +02:00			`"The best analytics are the ones that respect privacy while still giving you the insights you need." - Ethical Analytics Manifesto :icon{name="lucide:bar-chart"}:icon{name="lucide:sparkles"}`