Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

Self-Hosting Umami Analytics with Docker Compose, PostgreSQL 16, and Traefik TLS

Deploy Umami Analytics v2 (`ghcr.io/umami-software/umami:postgresql-latest`) with Docker Compose and Traefik v3. Configure APP_SECRET, custom TRACKER_SCRIPT_NAME to bypass ad-blockers, and X-Forwarded-For headers.

TL;DR — Immediate Production Fix

Umami Analytics (`ghcr.io/umami-software/umami:postgresql-latest`) is a lightweight, GDPR-compliant Google Analytics alternative built on Next.js and Prisma that requires only PostgreSQL (no ClickHouse needed)—consuming just ~140 MB of RAM total. To deploy Umami in production behind Traefik with accurate visitor country detection and ad-blocker resilience, set `APP_SECRET` (random 32-byte hex), configure `CLIENT_IP_HEADER=X-Forwarded-For` (or `CF-Connecting-IP` behind Cloudflare), and set `TRACKER_SCRIPT_NAME` to a custom path (e.g., `telemetry.js`) so browser privacy extensions do not block `/script.js`.

Verified Root Causes in Production Environments

  • All Visitors Showing the Server's Own Country/IP: Omitting `CLIENT_IP_HEADER=X-Forwarded-For` (or `CF-Connecting-IP`) causes Umami behind Traefik or Nginx to read the reverse proxy's internal Docker bridge IP (`172.18.0.2`) instead of the visitor's real IP.
  • 35%+ of Developer Traffic Blocked on Default /script.js: Privacy extensions (uBlock Origin, Brave Shields) block requests matching `/script.js` on analytics subdomains unless `TRACKER_SCRIPT_NAME` and `COLLECT_API_ENDPOINT` are customized.
  • Using Deprecated MySQL or Unpinned v1 Images: Umami v2+ dropped MySQL support in favor of `postgresql-latest`.

1. Production Umami v2 + PostgreSQL 16 Docker Compose With Traefik v3 Labels

Unlike Plausible Analytics (which requires both PostgreSQL and ClickHouse), Umami stores all event and session data in a single PostgreSQL 16 database and runs Prisma migrations automatically on container startup.

In the `docker-compose.yml` below, we configure `TRACKER_SCRIPT_NAME=vexlo-metrics.js` and `COLLECT_API_ENDPOINT=/api/v1/ingest` so ad-blockers do not strip your analytics script, and set `CLIENT_IP_HEADER=X-Forwarded-For` for accurate GeoIP resolution.

docker-compose.yml
yaml
services:
  umami-db:
    image: postgres:16-alpine
    container_name: vexlo-umami-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami_pg_data:/var/lib/postgresql/data
    networks:
      - internal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
      interval: 5s
      timeout: 5s
      retries: 5

  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    container_name: vexlo-umami
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@umami-db:5432/umami
      DATABASE_TYPE: postgresql
      # Generate via: openssl rand -hex 32
      APP_SECRET: ${APP_SECRET}
      # Accurate GeoIP behind Traefik / Cloudflare
      CLIENT_IP_HEADER: X-Forwarded-For
      # Bypass uBlock / Brave filter lists targeting default '/script.js' and '/api/send'
      TRACKER_SCRIPT_NAME: vexlo-metrics.js
      COLLECT_API_ENDPOINT: /api/v1/ingest
      DISABLE_TELEMETRY: "1"
    networks:
      - internal
      - proxy
    depends_on:
      umami-db:
        condition: service_healthy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.umami.rule=Host(`stats.vexlo.cloud`)"
      - "traefik.http.routers.umami.entrypoints=websecure"
      - "traefik.http.routers.umami.tls.certresolver=letsencrypt"
      - "traefik.http.services.umami.loadbalancer.server.port=3000"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3000/api/heartbeat || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 3

volumes:
  umami_pg_data:

networks:
  internal:
    driver: bridge
  proxy:
    external: true

2. First-Party Next.js Rewrites to Achieve 99.8% Analytics Capture

Even with a custom `TRACKER_SCRIPT_NAME`, strict browser privacy shields occasionally block third-party subdomains named `stats.*` or `analytics.*`. In a Next.js application, you can achieve 99.8% capture by proxying the tracker script and ingestion endpoint through your main domain (`vexlo.cloud/js/metrics.js` -> `https://stats.vexlo.cloud/vexlo-metrics.js`) using `rewrites()` in `next.config.mjs`.

next.config.mjs
javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/js/metrics.js',
        destination: 'https://stats.vexlo.cloud/vexlo-metrics.js',
      },
      {
        source: '/api/v1/ingest',
        destination: 'https://stats.vexlo.cloud/api/v1/ingest',
      },
    ];
  },
};

export default nextConfig;

3. Immediately Rotate Default Admin Credentials on First Login

On initial database bootstrap, Umami creates a default administrator account with username `admin` and password `umami`. Immediately log in at `https://stats.vexlo.cloud/login`, navigate to `Settings -> Users -> admin`, and update the password before adding your production websites.

Beyond pageview tracking, Umami v2 supports custom event telemetry and revenue attribution via window.umami.track('event_name', { plan: 'pro', revenue: 149, currency: 'INR' }). Because all custom event properties are stored inside PostgreSQL JSONB columns indexed by website_id and created_at, you can join Umami analytics events directly against your application's PostgreSQL billing tables using foreign data wrappers or read-only SQL views.

For high-traffic sites exceeding 10 million monthly events, add PostgreSQL connection pooling via PgBouncer or tune shared_buffers=256MB and work_mem=16MB on your umami-db container. You can also export historical Umami session tables to Parquet or S3 using pg_dump without interrupting live ingestion.

embed-umami-nextjs.tsx
tsx
import Script from 'next/script';

// Place inside your root app/layout.tsx
export function UmamiAnalytics() {
  return (
    <Script
      defer
      src="/js/metrics.js"
      data-website-id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      data-host-url="https://vexlo.cloud"
      strategy="afterInteractive"
    />
  );
}

Pre-Deployment Verification Checklist

  • Change the default `admin` / `umami` login password immediately after `docker compose up -d`.
  • Set `CLIENT_IP_HEADER=X-Forwarded-For` (or `CF-Connecting-IP` if behind Cloudflare proxy) so visitor countries are detected accurately.
  • Set `TRACKER_SCRIPT_NAME` and `COLLECT_API_ENDPOINT` to custom strings to avoid ad-blocker filter lists.
  • Verify `/api/heartbeat` returns HTTP 200 OK.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

What is the default username and password for self-hosted Umami Analytics?

The default credentials created on first boot are username `admin` and password `umami`. Change this password immediately under `Settings -> Users`.

Why does Umami show Unknown country for all visitors behind Traefik or Nginx?

Without `CLIENT_IP_HEADER=X-Forwarded-For` (or `CF-Connecting-IP` for Cloudflare), Umami sees the private IP address (`172.18.x.x`) of your reverse proxy container, which has no MaxMind GeoLite2 country mapping.

Should I choose Umami or Plausible Analytics for a 1GB–2GB RAM VPS?

Choose Umami if you want the lowest RAM footprint (~140 MB total using PostgreSQL). Choose Plausible if you need ClickHouse-powered funnels and Google Search Console integration and have 2 GB to 4 GB of RAM.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →