DockerSelf-Hosting

Umami with Docker: self-hosted website analytics without cookies (Linux, Windows, Mac)

Before you start

  • 21 min read

Boxes marked Run in terminal are what you type; plain text explains why. Check what you need first

What you get in one minute#

Umami is a free, open-source web analytics tool you run yourself: it counts visits, pages, referrers and events for your websites without cookies, and the data stays in your own PostgreSQL database.

Umami official logo

Logo: the official Umami project (github.com/umami-software/umami)

It suits a personal site, a blog or a small business site where you want to know what people read, without sending every visit to a third party. You paste one small script into your pages; Umami shows live and historical reports in its own dashboard.

WhatValue (official docs, read November 2026)
Current versionUmami v3.5.0, published 12 November 2026 (previous stable: v3.4.1, 23 October 2026)
Image to pinghcr.io/umami-software/umami:3.5.0 (tag, linux/amd64 and linux/arm64 manifests checked on the registry)
DatabasePostgreSQL only (v3 dropped MySQL); the official Compose file uses postgres:15-alpine
LicenceMIT (LICENSE at the release tag)
Time neededAbout 20 minutes (our estimate, not measured)
RAM and diskNot documented by the project; see "Performance and resources"
PortsUmami 3000 (the web app and the tracker); PostgreSQL 5432 stays inside Docker
Official docsumami.is/docs and the repository

At a glance:

  • What it is: a small web app plus a PostgreSQL database, in two containers.
  • What visitors load: one script (/script.js) that sends data to /api/send on your Umami address.
  • New in 3.5.0 and missing from old guides: APP_SECRET must be set explicitly, and the default login admin / umami must be replaced at first sign-in.
  • Platforms: Docker on Linux, Docker Desktop on Windows and Mac. The image has arm64 builds, so Apple Silicon and 64-bit Raspberry Pi systems are covered by the manifest.
  • Privacy: the docs say the tracker uses no cookies. The server itself calls the project for telemetry and update checks unless you turn them off (we do, below).
  • Honest limits: you patch and back it up yourself, there is no official hardware guide, and ad blockers can still block a self-hosted script.

How it fits together#

Visitors' browsers send page views to your Umami address; you open the same address to read the reports; Umami keeps everything in PostgreSQL.

Two-lane diagram: a visitor's browser loads script.js and sends data to /api/send through an optional HTTPS address (Caddy or Traefik, port 443) to the Umami app on port 3000, which writes visits to PostgreSQL on port 5432 in a folder named db; in the second lane you open the same HTTPS address to see the dashboard

Drawn for this guide from the official Compose file and docs. The HTTPS address (dashed) is optional while you test.

The tracker runs in the visitor's browser, so your Umami address must be reachable from where your visitors are. For a public website that means a public domain and HTTPS. For a site only you use at home, a local address is enough.

Before you start#

You need Docker with Compose and a machine that stays on. The project gives no minimum RAM or CPU, so we give none either.

SystemWhat you need
LinuxDocker Engine and the Compose plugin; openssl (for secrets). See our Docker on Ubuntu guide.
WindowsDocker Desktop (WSL2 backend) and PowerShell. curl.exe ships with Windows 10 and 11.
MacDocker Desktop (Intel or Apple Silicon) and Terminal. openssl and curl are included.

Check your tools (the same two commands work in PowerShell):

Run in terminalbash
docker --version
docker compose version

Windows has no openssl command by default, so Step 1 uses a PowerShell alternative.

Checklist:

  • [ ] Docker and Compose answer the two commands above
  • [ ] Port 3000 is free on the host (ss -ltn | grep 3000 on Linux)
  • [ ] A password manager ready for the admin password and the .env secrets
  • [ ] For the HTTPS section only: a domain with a DNS record for the server, and ports 80 and 443 free

Tested on: not run by us. The commands come from the official Compose file, docs and release notes read in November 2026.

Step 1: Create the folders and the secrets file#

Umami refuses to start without APP_SECRET. We also set a database password and the two-factor key. Everything lives in ~/docker_volumes/umami, as in all DIY Lab Hub guides.

Linux#

Run in terminalbash
mkdir -p ~/docker_volumes/umami/{db,backups}
cd ~/docker_volumes/umami
umask 077
cat > .env << EOF
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 24)
EOF
chmod 600 .env

Windows (PowerShell)#

Codepowershell
New-Item -ItemType Directory -Force "$HOME\docker_volumes\umami\db","$HOME\docker_volumes\umami\backups" | Out-Null
Set-Location "$HOME\docker_volumes\umami"
function New-Hex($n) { $b = New-Object byte[] $n; [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b); ($b | ForEach-Object { $_.ToString('x2') }) -join '' }
@("APP_SECRET=$(New-Hex 32)", "TWO_FACTOR_ENCRYPTION_KEY=$(New-Hex 32)", "POSTGRES_PASSWORD=$(New-Hex 24)") | Set-Content -Path .env -Encoding ascii

-Encoding ascii matters: older PowerShell adds a hidden byte-order mark to UTF-8 files, which can corrupt the first variable name.

Mac (Terminal)#

Same commands as Linux. umask 077 and chmod 600 keep the file private.

Check it worked. The file has three lines and each value is a long hex string. Do not print it into a chat or a screenshot.

Run in terminalbash
grep -c = ~/docker_volumes/umami/.env

On Windows run (Get-Content .env).Count. Both should print 3.

Tip: openssl rand -hex 32 is the command the official docs give for APP_SECRET and for the two-factor key. Hex values are safe inside a database URL; a password containing @ or / would break it.

Step 2: Write the Compose file and start Umami#

This is the official Compose file from the v3.5.0 tag with five changes: the image is pinned to 3.5.0 (the official file says latest), secrets come from .env (the official file ships umami as the database password), the database lives in ./db, the web port is bound to 127.0.0.1, and telemetry and update checks are off.

Linux#

Run in terminalbash
cd ~/docker_volumes/umami
cat > docker-compose.yml << 'EOF'
services:
  umami:
    image: ghcr.io/umami-software/umami:3.5.0
    container_name: umami
    init: true
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}@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 .env}
      DISABLE_TELEMETRY: "1"
      DISABLE_UPDATES: "1"
      PRIVATE_MODE: "1"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    container_name: umami-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
    volumes:
      - ./db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
EOF
docker compose up -d
docker compose ps

Windows (PowerShell)#

Save the same YAML as docker-compose.yml in $HOME\docker_volumes\umami (a text editor is simplest; keep the spaces), then:

Codepowershell
Set-Location "$HOME\docker_volumes\umami"
docker compose up -d
docker compose ps

If the umami-db log shows permission errors on the Windows folder, replace ./db:/var/lib/postgresql/data with the named volume umami-db-data:/var/lib/postgresql/data and add volumes: and umami-db-data: at the end of the file. That is the form the official file uses; we have not tested the folder variant on Windows.

Mac (Terminal)#

Same commands as Linux.

Check it worked. After about 30 seconds docker compose ps should list both containers as healthy. Then ask the app (Windows: curl.exe):

Run in terminalbash
curl -fsS http://127.0.0.1:3000/api/heartbeat

Expected, taken from the source code (src/app/api/heartbeat/route.ts), not from our run:

File contenttext
{"ok":true}

Tip: The heartbeat only proves the web app answers. It does not query the database. If login fails later, read docker compose logs umami --tail 100.

Four details in this file are worth knowing:

  • PRIVATE_MODE=1 disables all external calls, and also the website icons, because they come from DuckDuckGo. Remove it if you want icons.
  • DISABLE_TELEMETRY=1 and DISABLE_UPDATES=1 stop the anonymous telemetry pixel and the version check. You then watch the release page yourself.
  • init: true and the healthchecks come from the official file.
  • Compose reads .env only to fill the ${...} placeholders. The variables reach the app through the environment: block. Forgetting that is the oldest reported mistake (see Common mistakes).

Step 3: Log in and change the default password#

Linux#

On the server open http://127.0.0.1:3000. From another computer, open an SSH tunnel and then browse to http://localhost:3000 there:

Run in terminalbash
ssh -N -L 3000:127.0.0.1:3000 <your-user>@<your-server-address>

Windows (PowerShell)#

If Docker runs on your own PC, open http://localhost:3000. For a Linux server, run the same tunnel in PowerShell and keep the window open:

Run in terminalpowershell
ssh -N -L 3000:127.0.0.1:3000 <your-user>@<your-server-address>

Mac (Terminal)#

Same as Linux: open http://localhost:3000, or use the tunnel command above.

Sign in with username admin and password umami. Umami now forces you to choose a new password before you can continue (required since v3.5.0). Later you change it under your profile button, Settings, Security, Change password. The same page can switch on two-factor authentication; the TWO_FACTOR_ENCRYPTION_KEY from Step 1 is what makes that work.

Check it worked. After the new password you see the dashboard. Sign out and sign in again with the new password. The old one must fail.

Tip: Store the new password in a password manager now. We found no documented reset command in the official docs, so do not count on resetting it later.

Step 4: Add a website and install the tracker#

Linux#

In the dashboard open Websites, then Add website. Enter a Name and the real Domain (Umami uses it to filter your own site from referrers) and save. Then click Edit on that website and copy the code under Tracking code. Put it into the <head> of your site. It looks like this (placeholders are yours):

File contenthtml
<script defer src="https://<your-umami-address>/script.js" data-website-id="<your-website-id>"></script>

For a quick test without a website, send one event by hand. Create event.json and post it:

Run in terminalbash
cat > event.json << 'EOF'
{"type":"event","payload":{"hostname":"example.com","language":"en-US","screen":"1920x1080","title":"manual test","url":"/","website":"<your-website-id>"}}
EOF
curl -sS -X POST http://127.0.0.1:3000/api/send -H "Content-Type: application/json" -A "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36" --data @event.json

Windows (PowerShell)#

Same dashboard steps. For the manual test use curl.exe, which handles the JSON file better than the curl alias:

Codepowershell
'{"type":"event","payload":{"hostname":"example.com","language":"en-US","screen":"1920x1080","title":"manual test","url":"/","website":"<your-website-id>"}}' | Set-Content event.json -Encoding ascii
curl.exe -sS -X POST http://127.0.0.1:3000/api/send -H "Content-Type: application/json" -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0 Safari/537.36" --data "@event.json"

Mac (Terminal)#

Same as Linux. Any browser-like User-Agent text works.

Check it worked. The docs' sample answer to /api/send is a JSON object with cache, sessionId and visitId, and the dashboard then shows one visit under the website. For a real site, visit the page and the visit appears at once, as the docs say. The test request needs a browser-like User-Agent, or Umami drops it, and it needs your real website ID.

Tip: Visiting your own site counts as a visit. To skip yours, open the browser console on that site and run localStorage.setItem('umami.disabled', 1);. It works per website and per browser. IGNORE_IP (comma-separated addresses or CIDR ranges) excludes whole networks.

Single-page apps are tracked automatically; in Next.js use next/script, as the docs advise.

Put it behind HTTPS (with or without Traefik)#

For a public website you need HTTPS: an https:// page cannot load an http:// script, so a plain-HTTP Umami address breaks tracking. Local-only users can skip this section. Both routes need a domain with a DNS record for the server.

Umami has no public-URL setting in its environment list; the address is whatever your proxy serves. FORCE_SSL=1 only adds the HSTS header, it does not create HTTPS.

With Traefik#

This assumes Traefik v3 with the Docker provider, an external network called proxy and an entrypoint called https. The docs give no Traefik labels, so these are standard Traefik settings, not Umami docs. Create the network once if needed:

Run in terminalbash
docker network create proxy

In the Compose file remove the ports: block of umami and add the networks and labels:

File contentyaml
  umami:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"
      - "traefik.http.routers.umami.rule=Host(`umami.<your-domain>`)"
      - "traefik.http.routers.umami.entrypoints=https"
      - "traefik.http.routers.umami.tls=true"
      - "traefik.http.services.umami.loadbalancer.server.port=3000"

At the end of the file add:

File contentyaml
networks:
  proxy:
    external: true

Run docker compose up -d. Check it worked: curl -I https://umami.<your-domain>/script.js returns an HTTP status line over HTTPS.

Without Traefik: Caddy#

Caddy gets and renews its own certificates. Our Caddy guide explains it in more depth. Create its folders and the shared network:

Run in terminalbash
docker network create proxy
mkdir -p ~/docker_volumes/caddy/{conf,data,config}

Save as ~/docker_volumes/caddy/docker-compose.yml:

File contentyaml
services:
  caddy:
    image: caddy:2.11.9
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80/tcp"
      - "443:443/tcp"
      - "443:443/udp"
    volumes:
      - ./conf:/etc/caddy:ro
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true

The conf folder is mounted, not a single file, as Caddy's Docker notes advise. For a public domain save ~/docker_volumes/caddy/conf/Caddyfile:

File contenttext
umami.example.com {
    reverse_proxy umami:3000
}

At home with no public domain, use Caddy's own local certificate:

File contenttext
umami.home.arpa {
    tls internal
    reverse_proxy umami:3000
}

Give umami the proxy network exactly as in the Traefik route (remove its ports: block, add networks:), then start both stacks:

Run in terminalbash
cd ~/docker_volumes/caddy && docker compose up -d
cd ~/docker_volumes/umami && docker compose up -d

For tls internal, each device must trust Caddy's root certificate. Find and copy it from the container:

Run in terminalbash
docker exec caddy find /data -name root.crt
docker cp caddy:<path-from-find> ./caddy-root.crt

Install it as a trusted root: Windows "Trusted Root Certification Authorities", Mac Keychain Access with "Always Trust", Linux your distribution's CA store. Those OS steps are not from the Caddy docs. Visitors' devices would need the same, so use tls internal only for sites you alone view.

Check it worked. curl -I https://umami.example.com/script.js returns an HTTP status line. Windows runs it as curl.exe; Mac as curl in Terminal.

Tip: A certificate error usually means the DNS name in the Caddyfile or Traefik rule differs from the real DNS record, or port 80 or 443 does not reach the server.

Real visitor addresses behind a proxy#

If the reports show an internal address such as 172.x instead of a real visitor location, set TRUSTED_PROXIES (new in 3.5.0) to your proxy's network only. Umami reads the forwarding headers from right to left and skips trusted proxies. The docs warn against the private preset when visitors also use private addresses. Find the subnet to list:

Run in terminalbash
docker network inspect proxy --format '{{(index .IPAM.Config 0).Subnet}}'

Put that value into environment: as TRUSTED_PROXIES: "<subnet>". This is our reading of the docs; test it with a real visit.

Security and testing#

ControlHow
Admin passwordChange it at first login; add two-factor on the Security page.
Web port127.0.0.1:3000, or no host port behind a proxy. Never forward 3000 or 5432 on your router.
DatabaseNot published. PostgreSQL talks only to Umami over the Compose network.
Secrets.env with chmod 600; never in a repository. APP_SECRET signs login tokens; changing it signs everyone out.
Sign-upWe found no public sign-up switch in the environment list. Review the user list after setup.
DISABLE_LOGINDisables the login page entirely. It is not single sign-on; do not set it to "harden".
Single sign-onWe found no documented OIDC setup in the current docs. Use a proxy-level login if you need one.
Docker socketUmami needs none. Do not mount it.

Quick tests after each change:

Run in terminalbash
cd ~/docker_volumes/umami
docker compose ps
docker compose logs umami --tail 100
curl -fsS http://127.0.0.1:3000/api/heartbeat

What leaves the machine: with our settings, nothing on its own. By default the docs and source show three calls: a telemetry pixel (https://i.umami.is/a.png, carrying the version), an update check, and website icons from DuckDuckGo. PRIVATE_MODE=1 turns off all external calls. We did not audit every optional feature, so do not call this a guarantee.

What the dashboard stores: the docs list page views, referrer URLs, browsers, operating systems, device types and approximate location. Data you add yourself (event properties, distinct IDs) is your responsibility. Session replays and error tracking exist in 3.5.0 but are opt-in; error capture needs data-errors="true" on the script.

Common mistakes#

These come from the official docs, the release notes and GitHub reports we read; the issue numbers are in the Sources.

MistakeWhy it happensDo this instead
Starting v3.5.0 without APP_SECRETOlder versions fell back to DATABASE_URL; 3.5.0 removed that and rejects empty or placeholder valuesGenerate it with openssl rand -hex 32. For an old install that never set one, the docs say to set it to your exact old DATABASE_URL once, which keeps logins working
Copying the official file with latest and password umamiThe shipped file is an example; latest moves when you pullPin 3.5.0, set your own database password
Keeping admin / umamiEveryone knows it; 3.5.0 forces a change, older installs did notChange it at first login and add two-factor
Environment variable not found: DATABASE_URLA .env file next to Compose only fills ${...} placeholders (issue 449)Pass every variable in environment:
localhost in DATABASE_URL inside DockerThe docs' localhost example is for the source install; in a container, localhost is the app itselfUse the service name: @db:5432/umami
Using MySQL or old image namesVersion 1 and 2 guides use mikecao/umami:mysql-latest and DATABASE_TYPE=mysql (issue 1174); v3 is PostgreSQL onlyUse ghcr.io/umami-software/umami and PostgreSQL
Jumping versions without reading notesA v1 database makes v2 stop at start: Umami v1 tables detected (issue 1985)Read the release notes, back up, upgrade one major at a time
Setting BASE_PATH at runtime to serve under /analyticsThe docs list it as a build-time setting (discussion 858)Use a subdomain such as umami.<your-domain>
Counting your own visitsThe tracker cannot tell you from a visitorlocalStorage.setItem('umami.disabled', 1) or IGNORE_IP
Script blocked by an ad blockerSome lists block "analytics" or tracking products by nameSee "Ad blockers and the script name" below
Never backing up .envAPP_SECRET and the two-factor key are not in the databaseBack up .env with the dump, and keep both private
AI assistants: inventing settings such as DISABLE_SIGNUP, NEXTAUTH_URL, HASH_SALT, PUBLIC_URLThese are absent from the current environment list; some are version 1 leftoversUse only names from the environment page
AI assistants: /api/collect, DISABLE_TELEMETRY=0, or "FORCE_SSL gives HTTPS"The collection route is /api/send; the source tests whether the telemetry variable is set, not its text; FORCE_SSL only adds HSTSDelete the line to turn telemetry back on; use a proxy for HTTPS

Tip: Before copying any Umami Compose file from a blog, look for APP_SECRET. If the file lacks it, or uses MySQL, it is for an old version.

Tip: After every config change run docker compose logs umami --tail 100. The exact error is printed there.

Tip: Change one thing at a time: first get the plain 127.0.0.1:3000 page working, then HTTPS, then tracking, then ad-blocker settings.

Ad blockers and the script name#

The docs say ad blockers may block /script.js and /api/send, and that some lists block anything with "analytics" in the name. Besides proxying the script through your own site, a self-hosted instance can rename both. Add this to the environment: of umami, using your own words:

File contentyaml
      TRACKER_SCRIPT_NAME: "stats-lib.js"
      COLLECT_API_ENDPOINT: "/api/stats"

Recreate with docker compose up -d, change your site's <script src> to the new name, and open the browser's Network tab: both requests should succeed. No renaming is perfect; the lists keep changing.

Troubleshooting#

ProblemSolution
Container restarts and the log shows an APP_SECRET error.env is missing, empty or in another folder; check it sits next to docker-compose.yml and has an APP_SECRET= line
Page loads but login failsWrong password, or the database is not ready; docker compose logs umami --tail 100
Unable to connect to the database.Wrong DATABASE_URL or password, or db not healthy yet: docker compose ps and docker compose logs db
Dashboard empty after adding the scriptWrong website ID, an ad blocker, or the page cannot reach Umami; open the browser Network tab
Mixed content error in the browser consoleAn https:// site loads http:// Umami; put Umami behind HTTPS
Blank dashboard, /_next/static/chunks/... return 404A proxy or cache serves another build (issue 2716); clear caches, recreate the containers
Wrong visitor country or IPSet TRUSTED_PROXIES as in the HTTPS section
Reports slow after a big upgradeRun ANALYZE; in PostgreSQL (docs); see Updates
Cannot reach it from other machinesThe port is bound to 127.0.0.1 on purpose; use the proxy or the tunnel

Exact error texts#

APP_SECRET must be set to a non-empty secret and cannot use the default placeholder. The text comes from src/lib/app-secret.ts. Put a generated value into .env and recreate the container.

Error: P3009 after an update (issue 2206, a MySQL-era report): a failed migration blocks later ones. Restore your pre-update backup rather than editing migration tables by hand.

Error loading shared library libssl.so.1.1: No such file or directory (issue 3115, v2.15.0): an old image problem. Use the current pinned tag.

time zone "America/Buenos_Aires" not recognized (issue 4739, v3.4.1): a timezone naming bug marked fixed in v3.5.0. Upgrade, or pick another zone in Settings.

Environment variable not found: DATABASE_URL. (issue 449): the variable never reached the container; see Common mistakes.

Unable to connect to the database. (issue 2014): the app could not reach PostgreSQL. Check the password, the host name db and docker compose logs db.

Known bugs (November 2026)#

3.5.0 is four days old as we write. In the open issues we saw no start-up or data-loss report. Open issue 4763 says the Docker startup script forces HOSTNAME=0.0.0.0, which only matters for IPv6-only or dual-stack Kubernetes setups. If a 3.5.0 problem hits you, the fallback is 3.4.1 (a security hotfix), but its database must come from a backup taken before the upgrade: 3.5.0 adds migration 27_add_error_tracking, and the docs do not describe downgrading in place.

Updates and backups#

Update. Read the release notes, back up, change the tag, then:

Run in terminalbash
cd ~/docker_volumes/umami
docker compose pull
docker compose up --force-recreate -d
docker compose logs umami --tail 100

Windows and Mac: the same commands in PowerShell or Terminal (on Windows start with Set-Location "$HOME\docker_volumes\umami"). The official update page uses these two Compose commands. Migrations run automatically at container start. After a major upgrade the docs advise running ANALYZE; once to refresh PostgreSQL statistics (safe on a live database):

Run in terminalbash
docker compose exec db psql -U umami -d umami -c "ANALYZE;"

Back up. The docs give no backup commands, so this is our recipe using the official service and user names. The dump is made inside the container and copied out, which avoids PowerShell damaging binary output.

Linux#

Run in terminalbash
cd ~/docker_volumes/umami
cat > backup.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd ~/docker_volumes/umami
stamp=$(date +%F)
docker compose exec -T db pg_dump -U umami -Fc -f /tmp/umami.dump umami
docker compose cp db:/tmp/umami.dump "backups/umami-$stamp.dump"
docker compose exec -T db rm /tmp/umami.dump
cp .env "backups/env-$stamp"
chmod 600 backups/*
EOF
chmod +x backup.sh
./backup.sh
( crontab -l 2>/dev/null; echo "0 3 * * * $HOME/docker_volumes/umami/backup.sh" ) | crontab -

Windows (PowerShell)#

Codepowershell
Set-Location "$HOME\docker_volumes\umami"
@'
Set-Location "$HOME\docker_volumes\umami"
$stamp = Get-Date -Format yyyy-MM-dd
docker compose exec -T db pg_dump -U umami -Fc -f /tmp/umami.dump umami
docker compose cp db:/tmp/umami.dump "backups\umami-$stamp.dump"
docker compose exec -T db rm /tmp/umami.dump
Copy-Item .env "backups\env-$stamp"
'@ | Set-Content backup.ps1 -Encoding ascii
.\backup.ps1
schtasks /Create /SC DAILY /ST 03:00 /TN "umami-backup" /TR "powershell.exe -NoProfile -ExecutionPolicy Bypass -File `"$HOME\docker_volumes\umami\backup.ps1`""

Mac (Terminal)#

Same script and cron line as Linux. macOS may ask you to allow cron in Privacy settings. Docker Desktop must be running at 03:00, so a laptop that sleeps will skip the backup.

Copy the backups folder to another machine too; our restic guide shows one way. Treat the files as secret.

Restore test. Restore into a throwaway database, never over the live one, and count rows:

Run in terminalbash
cd ~/docker_volumes/umami
docker compose exec -T db createdb -U umami umami_restore_test
docker compose cp backups/umami-<date>.dump db:/tmp/restore.dump
docker compose exec -T db pg_restore -U umami -d umami_restore_test --no-owner /tmp/restore.dump
docker compose exec -T db psql -U umami -d umami_restore_test -c "SELECT count(*) FROM website_event;"
docker compose exec -T db dropdb -U umami umami_restore_test

Windows and Mac run the same docker compose lines (on Windows write backups\umami-<date>.dump). A real restore stops the app first (docker compose stop umami), runs pg_restore --clean --if-exists -d umami instead, then starts it. We did not run these commands; do the test once before you rely on it.

Performance and resources#

The docs publish no RAM, CPU or disk figures and we measured none, so we give none. Measure on your own server:

  • Live use: docker stats umami umami-db shows memory and CPU for both containers.
  • Disk: du -sh ~/docker_volumes/umami/db (Windows: Get-ChildItem db -Recurse | Measure-Object Length -Sum). It grows with every event, and faster if you turn on session replays.
  • Slow reports: run ANALYZE; after a major upgrade (docs). REDIS_URL is optional and off unless you set it; add Redis only for a measured need.

FAQ#

Does Umami need a GPU or an AI model? No. It is a web app and a database. The project documents an optional read-only endpoint for the Model Context Protocol (off by default, MCP_ENABLED=1); analytics do not need it.

Is it really cookie-free and GDPR-compliant? The docs say the tracker uses no cookies, and that GDPR compliance depends on your configuration. Self-hosting does not decide that for you; check what you add (events, distinct IDs, replays).

Can I use MySQL or SQLite? No. Since v3.0.0 (7 November 2025) only PostgreSQL is supported; the source install needs v12.14 or newer.

Can it run on a Raspberry Pi or Apple Silicon? The 3.5.0 image has linux/arm64, so 64-bit systems should work. The project gives no Raspberry Pi sizing, and we did not test one.

Can I track several websites? Yes. Add each under Websites; each gets its own ID and script tag.

Is there a cloud version? Yes, Umami Cloud is a separate hosted product. This guide covers only self-hosting.

Sources#

Checked against the official docs on 2026-11-16.