This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.

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:3000 so only the reverse proxy can reach it.
  • One named volume: umami-db-data mounted 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:

  1. Sign in as admin / umami and change the password to something long and unique.
  2. Enable two-factor authentication in the profile settings — this is what TWO_FACTOR_ENCRYPTION_KEY protects. If you rotate that key later, existing 2FA enrollments break.
  3. Create a dedicated non-admin user for daily dashboard access and keep admin for break-glass only.
  4. 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.
  5. Block direct access to port 3000 from the internet (the 127.0.0.1 bind 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/umami login 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_SECRET and TWO_FACTOR_ENCRYPTION_KEY are not interchangeable. Rotating APP_SECRET logs everyone out (annoying but recoverable). Rotating TWO_FACTOR_ENCRYPTION_KEY makes 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.

Originally published with full interactive benchmark metrics and server sizing notes at https://benchrun.pages.dev/self-host-umami-docker-compose/.