How to Install Umami Analytics on Docker (2026 Guide)

Umami is a simple, fast, privacy-focused web analytics tool and a solid Google Analytics alternative. It’s MIT-licensed, has over 37,000 GitHub stars, and collects only the metrics you need without tracking your visitors. If you want to compare options, Plausible and Matomo are similar self-hosted analytics tools. You can also install Plausible Analytics with a similar Docker setup.

With Google Analytics 4 and GDPR enforcement in the EU, self-hosted web analytics has become the default for operators who want full data ownership. Google Analytics scripts are heavy and slow down your site. Umami adds less than 2KB of overhead.

This guide covers how to install Umami Analytics on Docker with Docker Compose, including tracker setup, ad-blocker bypass, upgrades, and backups. Umami v3 shipped in November 2025 with a new UI, heatmaps, session replay, and it’s now PostgreSQL-only (MySQL support was dropped).

You can find more free open source self-hosted apps at toolhunt.net self hosted section.

Steps to install Umami Analytics with Docker Compose

We’ll deploy Umami on a VPS with Docker Compose, then configure Cloudflare Tunnels for public access with SSL. The video walkthrough below covers the full process.

1. Prerequisites

2. Docker Compose file for Umami

Below are two compose files. The first is a clean setup with no backup, use this if you plan to back up with a cron-based pg_dump (recommended). The second adds a tiredofit/db-backup sidecar for automatic scheduled dumps.

services:
  umami:
    image: docker.umami.is/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@umami-db:5432/${POSTGRES_DB}
      APP_SECRET: ${APP_SECRET}
      DISABLE_TELEMETRY: ${DISABLE_TELEMETRY:-1}
    depends_on:
      umami-db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5

  umami-db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      TZ: UTC
    volumes:
      - ./umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

services:
  umami:
    image: docker.umami.is/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@umami-db:5432/${POSTGRES_DB}
      APP_SECRET: ${APP_SECRET}
      DISABLE_TELEMETRY: ${DISABLE_TELEMETRY:-1}
    depends_on:
      umami-db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5

  umami-db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      TZ: UTC
    volumes:
      - ./umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

  umami-db-backup:
    container_name: umami-db-backup
    image: tiredofit/db-backup
    volumes:
      - ./backups:/backup
    environment:
      DB_TYPE: postgres
      DB_HOST: umami-db
      DB_NAME: ${POSTGRES_DB}
      DB_USER: ${POSTGRES_USER}
      DB_PASS: ${POSTGRES_PASSWORD}
      DB_BACKUP_INTERVAL: 720
      DB_CLEANUP_TIME: 72000
      CHECKSUM: SHA1
      COMPRESSION: GZ
      CONTAINER_ENABLE_MONITORING: false
    depends_on:
      umami-db:
        condition: service_healthy
    restart: always

If you need to run multiple PostgreSQL databases on the same host, you can consolidate them into a single Postgres container to save memory.

3. Configure the .env file

Create a .env file in the same directory as your compose file (or add the variables in Dockge’s environment section).

POSTGRES_USER=umami
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=umami
APP_SECRET=run-openssl-rand-hex-32-to-generate
DISABLE_TELEMETRY=1

4. Deploy Umami

If using Dockge, add a name for your stack and hit deploy. With plain Docker Compose:

docker compose up -d

Verify both containers are healthy:

docker compose ps

You should see both umami and umami-db with status healthy. Check the Umami logs to confirm migrations ran:

docker compose logs -f umami

Healthy output looks like: All migrations have been successfully applied followed by the server listening on port 3000.

Access Umami at http://your-vps-ip:3000. Log in with the default credentials:

• Username: admin
• Password: umami

Quick verification with curl:

curl http://localhost:3000/api/heartbeat
# Should return: OK

5. Configure Cloudflare Tunnels for Umami

Go to Access → Tunnels in the Cloudflare dashboard, choose your tunnel, and add a hostname mapping a domain or subdomain to the Umami service on port 3000.

You can also check Setup CloudPanel as Reverse Proxy with Docker and Dockge to use CloudPanel as a reverse proxy to your Docker containers, or self-host with Docker and Cloudflare Tunnels for another deployment example.

6. Add your first website to Umami

After the tunnel is configured, access Umami at your domain. Log in and go to Settings in the header. You’ll see a button to add a website:

After adding a website, click Edit Website (or go to Settings) to find your tracking code. You can paste this into your site’s <head>.

Umami tracking code and tracker configuration

Once your website is added, Umami gives you a tracking script. Here’s how to use it and what options are available.

Basic tracking script

The standard embed looks like this:

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

• data-website-id (the UUID of the website you added in Umami, visible in the tracking code snippet)
• data-host-url (set this if your tracker domain differs from the dashboard domain, e.g., you serve the script from a CDN)

Custom events and advanced options

Umami supports both programmatic and declarative event tracking.

Programmatic (call from JavaScript):

// Track a custom event with properties
umami.track("signup", { plan: "pro", source: "header" });

Declarative (add HTML attributes to any element):

<button data-umami-event="click-download" data-umami-file="whitepaper.pdf">
  Download
</button>

Other useful data attributes:

If you’re using an Astro site, see Plausible Analytics for Astro with Cloudflare Workers for a related analytics integration approach.

Bypass ad blockers

Ad-blockers target two default paths: /script.js and /api/send. You can rename both with environment variables:

TRACKER_SCRIPT_NAME=custom-tracker
COLLECT_API_ENDPOINT=/api/collect

Add these to the umami service environment in your compose file, then restart. Update your tracking script src to match:

<script
  defer
  src="https://your-domain.com/custom-tracker.js"
  data-website-id="your-website-id"
></script>

environment:
  DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@umami-db:5432/${POSTGRES_DB}
  APP_SECRET: ${APP_SECRET}
  DISABLE_TELEMETRY: ${DISABLE_TELEMETRY:-1}
  TRACKER_SCRIPT_NAME: my-stats
  COLLECT_API_ENDPOINT: /api/c
  CLIENT_IP_HEADER: cf-connecting-ip

<script
  defer
  src="https://stats.yourdomain.com/my-stats.js"
  data-website-id="your-website-id"
></script>

How to update Umami Analytics on Docker

Standard updates (same major version)

For minor updates within v3.x:

# 1. Back up the database first
docker compose exec -T umami-db pg_dump -U umami umami | gzip > backups/umami-$(date +%F-%H%M).sql.gz

# 2. Pull the latest image
docker compose pull

# 3. Recreate containers
docker compose up -d --force-recreate

# 4. Verify: look for "All migrations have been successfully applied"
docker compose logs -f umami

Upgrading from Umami v2 to v3

Steps:

# 1. Back up
docker compose exec -T umami-db pg_dump -U umami umami > umami-backup-$(date +%F-%H%M).sql

# 2. Pull and recreate
docker compose pull
docker compose up -d --force-recreate umami

# 3. Watch logs for migration output
docker compose logs -f umami

# 4. Run ANALYZE on PostgreSQL (critical after major upgrades)
docker compose exec -T umami-db psql -U umami umami -c "ANALYZE;"

The ANALYZE command updates PostgreSQL’s query planner statistics after schema migrations. The official Umami docs recommend this. Without it, dashboard queries can become slow after a major upgrade.

After upgrading, old Docker images accumulate on disk. You can clean up Docker disk space to reclaim storage.

Database backup and restore

docker compose exec -T umami-db pg_dump -U umami umami | gzip > backups/umami-$(date +%F).sql.gz

0 3 * * * cd /path/to/umami && docker compose exec -T umami-db pg_dump -U umami umami | gzip > backups/umami-$(date +\%F).sql.gz

gunzip < backups/umami-YYYY-MM-DD.sql.gz | docker compose exec -T umami-db psql -U umami umami

# Find the latest backup
ls -lt backups/

# Restore it
zcat backups/umami-db-*.sql.gz | docker compose exec -T umami-db psql -U umami umami

Verify and troubleshoot your Umami installation

If you want to monitor your server resources alongside Umami, set up a lightweight monitoring stack.

docker compose exec -T umami-db psql -U umami umami -c "ANALYZE;"

CLIENT_IP_HEADER=cf-connecting-ip

deploy:
  resources:
    limits:
      memory: 256M

Umami v3: what’s new

PostgreSQL v12.14+ is required for v3. The postgres:15-alpine image used in this guide satisfies this.

Conclusion

You now have Umami Analytics installed on Docker, with a working tracker configuration, ad-blocker bypass options, and a solid upgrade and backup workflow. Umami is free, uses about 300MB of RAM total, and gives you full ownership of your analytics data. No third-party access, no GDPR headaches.

Key things to remember: back up before every major upgrade, pin your image version for reproducibility, and change the default password immediately after first login. If you want to explore other options, you can also install Plausible Analytics with a similar Docker approach, or monitor your server resources to keep an eye on your VPS.