# Umami Web Analytics

> Umami simple, privacy-focused alternative to Google Analytics.

- Category: Monitoring & Observability
- Difficulty: beginner
- Components: umami, postgres
- Tags: umami, analytics, privacy, web-analytics, gdpr
- Source: https://docker.recipes/monitoring/umami-analytics

## Overview

Umami is a modern, open-source web analytics platform that emerged as a privacy-first alternative to Google Analytics, focusing on simplicity without sacrificing essential insights. Developed with GDPR compliance at its core, Umami collects only the data you need - page views, referrers, and basic visitor metrics - while respecting user privacy through cookieless tracking and no personal data collection. The platform provides clean, intuitive dashboards that deliver actionable insights without the complexity and privacy concerns of traditional analytics solutions.

This deployment combines Umami with PostgreSQL to create a robust, self-hosted analytics infrastructure that handles high-traffic websites with enterprise-grade data reliability. PostgreSQL's ACID compliance ensures analytics data integrity, while its advanced indexing capabilities enable fast query performance even with millions of page views. The database's JSON support allows Umami to efficiently store flexible event data alongside structured analytics metrics, providing the perfect balance of relational integrity and document flexibility.

This stack is ideal for privacy-conscious organizations, web agencies managing multiple client sites, and developers who need reliable analytics without vendor lock-in or data sharing concerns. Unlike cloud-based solutions, this configuration gives you complete control over your analytics data, making it perfect for companies with strict data governance requirements, European businesses needing GDPR compliance, or anyone seeking to reduce dependence on big tech analytics platforms.

## Features

- Cookieless tracking system that complies with GDPR, CCPA, and PECR without requiring consent banners
- Real-time analytics dashboard showing live visitor activity, page views, and traffic sources
- Custom event tracking for button clicks, form submissions, and user interactions beyond page views
- Multi-website support allowing unlimited sites managed from a single Umami instance
- PostgreSQL-backed data persistence with automatic schema migrations and data integrity guarantees
- Lightweight 2KB tracking script that loads faster than Google Analytics with minimal performance impact
- Built-in UTM parameter tracking for campaign attribution and marketing analytics
- Geographic and device analytics without storing personally identifiable information

## Use cases

- Small to medium businesses replacing Google Analytics with a privacy-compliant solution
- Web development agencies managing analytics for multiple client websites from one dashboard
- E-commerce sites tracking product page performance and conversion funnels without cookies
- Content creators and bloggers monitoring article performance and audience engagement
- SaaS companies analyzing feature usage and user behavior while maintaining data sovereignty
- Educational institutions tracking website usage while protecting student privacy
- Government and healthcare organizations requiring strict data privacy compliance

## Prerequisites

- Minimum 1GB RAM for PostgreSQL database operations and query performance
- Port 3000 available for Umami web interface access
- Basic understanding of environment variable configuration for database credentials
- Domain name or reverse proxy setup for production SSL termination
- Knowledge of PostgreSQL backup procedures for analytics data protection

## docker-compose.yml

```yaml
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: umami
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/umami
      - DATABASE_TYPE=postgresql
      - APP_SECRET=${APP_SECRET}
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - umami-network

  postgres:
    image: postgres:16-alpine
    container_name: umami-db
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=umami
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - umami-network

volumes:
  postgres_data:

networks:
  umami-network:
    driver: bridge
```

## .env

```bash
# Umami Analytics
POSTGRES_USER=umami
POSTGRES_PASSWORD=umami_password
APP_SECRET=your-random-app-secret
```

## Usage notes

- Dashboard at http://localhost:3000
- Default login: admin / umami
- Change password after first login
- GDPR compliant, no cookies
- Lightweight tracking script

## Troubleshooting

- Database connection failed: Verify POSTGRES_USER and POSTGRES_PASSWORD match in both services
- Umami shows 'Invalid credentials' on first login: Use default admin/umami, then change password immediately
- Tracking script not recording visits: Check website URL matches exactly in Umami dashboard settings
- PostgreSQL container won't start: Ensure postgres_data volume has correct permissions (postgres:postgres ownership)
- High memory usage over time: Configure PostgreSQL shared_buffers and work_mem based on available system resources
- Analytics data missing after restart: Verify postgres_data volume is properly mounted and persistent

