Umami Web Analytics

beginner

Umami simple, privacy-focused alternative to Google 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.

Key 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

Common Use Cases

1Small to medium businesses replacing Google Analytics with a privacy-compliant solution
2Web development agencies managing analytics for multiple client websites from one dashboard
3E-commerce sites tracking product page performance and conversion funnels without cookies
4Content creators and bloggers monitoring article performance and audience engagement
5SaaS companies analyzing feature usage and user behavior while maintaining data sovereignty
6Educational institutions tracking website usage while protecting student privacy
7Government 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

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  umami: 
3    image: ghcr.io/umami-software/umami:postgresql-latest
4    container_name: umami
5    environment: 
6      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/umami
7      - DATABASE_TYPE=postgresql
8      - APP_SECRET=${APP_SECRET}
9    ports: 
10      - "3000:3000"
11    depends_on: 
12      postgres: 
13        condition: service_healthy
14    networks: 
15      - umami-network
16
17  postgres: 
18    image: postgres:16-alpine
19    container_name: umami-db
20    environment: 
21      - POSTGRES_USER=${POSTGRES_USER}
22      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
23      - POSTGRES_DB=umami
24    volumes: 
25      - postgres_data:/var/lib/postgresql/data
26    healthcheck: 
27      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
28      interval: 10s
29      timeout: 5s
30      retries: 5
31    networks: 
32      - umami-network
33
34volumes: 
35  postgres_data: 
36
37networks: 
38  umami-network: 
39    driver: bridge

.env Template

.env

1# Umami Analytics
2POSTGRES_USER=umami
3POSTGRES_PASSWORD=umami_password
4APP_SECRET=your-random-app-secret

Usage Notes

1Dashboard at http://localhost:3000
2Default login: admin / umami
3Change password after first login
4GDPR compliant, no cookies
5Lightweight tracking script

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

umami

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

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

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  umami:
5    image: ghcr.io/umami-software/umami:postgresql-latest
6    container_name: umami
7    environment:
8      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/umami
9      - DATABASE_TYPE=postgresql
10      - APP_SECRET=${APP_SECRET}
11    ports:
12      - "3000:3000"
13    depends_on:
14      postgres:
15        condition: service_healthy
16    networks:
17      - umami-network
18
19  postgres:
20    image: postgres:16-alpine
21    container_name: umami-db
22    environment:
23      - POSTGRES_USER=${POSTGRES_USER}
24      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
25      - POSTGRES_DB=umami
26    volumes:
27      - postgres_data:/var/lib/postgresql/data
28    healthcheck:
29      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
30      interval: 10s
31      timeout: 5s
32      retries: 5
33    networks:
34      - umami-network
35
36volumes:
37  postgres_data:
38
39networks:
40  umami-network:
41    driver: bridge
42EOF
43
44# 2. Create the .env file
45cat > .env << 'EOF'
46# Umami Analytics
47POSTGRES_USER=umami
48POSTGRES_PASSWORD=umami_password
49APP_SECRET=your-random-app-secret
50EOF
51
52# 3. Start the services
53docker compose up -d
54
55# 4. View logs
56docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/umami-analytics/run | bash

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

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

umamipostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download