2026-11-17 · umami · analytics · docker · postgresql
Self-Host Umami Analytics with Docker Compose
Run Umami, the privacy-first Google Analytics alternative, with PostgreSQL in Docker Compose. Secure setup, reverse proxy, backups, and updates.
- Total RAM
- 212.3 MB
- Startup
- 109.7 s
- Port
- 3000
- HTTP
- 200
umami 165.9 MB
· db 46.4 MB
What Umami does and what it needs
Umami is a self-hosted, cookie-free web analytics platform. It tracks pageviews, referrers, events, and funnels without collecting personal data, so you can drop Google Analytics and keep your visitors’ data on your own server. The app is a Next.js frontend backed by PostgreSQL; there is no Redis or message queue to babysit.
The official Compose file pairs the ghcr.io/umami-software/umami:latest image with postgres:15-alpine. Two secrets are mandatory: APP_SECRET (signs sessions) and TWO_FACTOR_ENCRYPTION_KEY (encrypts 2FA seeds). The upstream project does not publish a minimum RAM figure. In practice an idle instance with a few low-traffic sites runs comfortably in a 1 GB VPS; memory scales with concurrent dashboard users and the size of the events table, not with raw pageview count alone.
Prerequisites, ports, and volume constraints
- A Linux VPS with Docker Engine 24+ and the Compose v2 plugin (
docker compose version). - A domain name pointed at the server if you want HTTPS (recommended).
- Port 3000 is the only port Umami listens on. We bind it to
127.0.0.1:3000so only the reverse proxy can reach it. - One named volume:
umami-db-datamounted at/var/lib/postgresql/data. That volume holds every pageview and user account — back it up, never delete it casually. - PostgreSQL is not exposed to the host; the app talks to it over the internal Compose network as
db:5432.
If you want to test without a domain, either SSH-tunnel (ssh -L 3000:127.0.0.1:3000 user@server) or temporarily change the port mapping to "3000:3000" — but put it back before going live.
Production Docker Compose setup
Create a project directory and generate the two secrets first:
mkdir -p ~/umami && cd ~/umami
openssl rand -hex 32 # APP_SECRET
openssl rand -hex 32 # TWO_FACTOR_ENCRYPTION_KEY
openssl rand -hex 24 # DB_PASSWORD
Write the .env file (paste the values you just generated):
cat <<'EOF' > .env
APP_SECRET=paste-first-hex-here
TWO_FACTOR_ENCRYPTION_KEY=paste-second-hex-here
DB_PASSWORD=paste-third-hex-here
TZ=UTC
EOF
chmod 600 .env
Now the Compose file. It mirrors the upstream layout but pulls the database password from .env and binds the web port to localhost:
cat <<'EOF' > compose.yml
services:
umami:
image: ghcr.io/umami-software/umami:latest
ports:
- "127.0.0.1:3000:3000"
environment:
DATABASE_URL: postgresql://umami:${DB_PASSWORD}@db:5432/umami
APP_SECRET: ${APP_SECRET:?Set APP_SECRET in your .env file}
TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY:?Set TWO_FACTOR_ENCRYPTION_KEY in your .env file}
TZ: ${TZ:-UTC}
depends_on:
db:
condition: service_healthy
init: true
restart: always
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat || exit 1"]
interval: 10s
timeout: 5s
retries: 5
db:
image: postgres:15-alpine
environment:
POSTGRES_DB: umami
POSTGRES_USER: umami
POSTGRES_PASSWORD: ${DB_PASSWORD:?Set DB_PASSWORD in your .env file}
TZ: ${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
volumes:
umami-db-data:
EOF
Start the stack and watch the logs until the healthcheck flips to healthy:
docker compose up -d
docker compose ps
docker compose logs -f umami
On first boot Umami creates the schema and a default login: username admin, password umami. You will be forced to change it on first sign-in — do that immediately, before exposing the app.
Reverse proxy, HTTPS, and first-run hardening
Umami is a plain HTTP app on port 3000. It does not need WebSocket upgrades for the dashboard, but it does need correct X-Forwarded-* headers so the UI generates https:// links and the tracking script reports the right host. A minimal Caddyfile on the host:
analytics.example.com {
encode gzip
reverse_proxy 127.0.0.1:3000 {
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-Host {host}
}
}
Reload Caddy (systemctl reload caddy) and confirm https://analytics.example.com/api/heartbeat returns {"ok":true}. For Nginx, use proxy_pass http://127.0.0.1:3000; plus proxy_set_header X-Forwarded-Proto $scheme; and proxy_set_header Host $host;. The tracking endpoint (/api/send) accepts small JSON payloads, so the default 1 MB body limit is fine; if you push custom events with large metadata, raise client_max_body_size to 2 MB.
First-run hardening checklist:
- Sign in as
admin/umamiand change the password to something long and unique. - Enable two-factor authentication in the profile settings — this is what
TWO_FACTOR_ENCRYPTION_KEYprotects. If you rotate that key later, existing 2FA enrollments break. - Create a dedicated non-admin user for daily dashboard access and keep
adminfor break-glass only. - Add your first website in the UI, copy the tracking snippet, and verify a pageview lands in the Realtime view before pointing real traffic at it.
- Block direct access to port 3000 from the internet (the
127.0.0.1bind already does this) and keep the firewall closed on 3000.
Updating, backups, and common pitfalls
Update by pulling the new image and recreating the container. The database schema migrates automatically on startup:
docker compose pull
docker compose up -d --force-recreate
docker compose logs -f umami # watch for migration output
Back up the umami-db-data volume with a logical dump — safer than copying raw Postgres files while the container is running:
docker compose exec -T db pg_dump -U umami umami | gzip > umami-$(date +%F).sql.gz
Restore with gunzip -c umami-YYYY-MM-DD.sql.gz | docker compose exec -T db psql -U umami umami. Store dumps off the VPS.
Two pitfalls worth knowing:
- The default
admin/umamilogin is real. The README is explicit: the first build creates that account and forces a password change. If you expose the app before signing in, anyone can claim it. Do the first login over the SSH tunnel or immediately after the proxy is up. APP_SECRETandTWO_FACTOR_ENCRYPTION_KEYare not interchangeable. RotatingAPP_SECRETlogs everyone out (annoying but recoverable). RotatingTWO_FACTOR_ENCRYPTION_KEYmakes existing 2FA secrets undecryptable, locking out every 2FA user. Back both values up alongside your database dump.
If the umami container restarts in a loop, check docker compose logs db first — the app waits on the Postgres healthcheck, and a wrong DB_PASSWORD in .env (or a stale volume initialized with the old password) is the usual cause. Changing POSTGRES_PASSWORD on an existing volume does nothing; you must either ALTER USER inside the container or recreate the volume from a backup.
Measured in our sandbox run: total memory 212.3 MB (sum of per-container peaks over a 30s idle window after startup) across 2 containers; largest container 165.9 MB; published port(s) 3000; HTTP probe returned 200. The run took 109.7s including the image download. Required secret(s) APP_SECRET, DB_PASSWORD, POSTGRES_DB, POSTGRES_USER, TWO_FACTOR_ENCRYPTION_KEY were generated for the test run, as the tutorial instructs. Container breakdown: umami 165.9 MB, db 46.4 MB.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.