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.
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.
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: true2. 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`.
/** @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.
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.
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.