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.

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.
| What | Value (official docs, read November 2026) |
|---|---|
| Current version | Umami v3.5.0, published 12 November 2026 (previous stable: v3.4.1, 23 October 2026) |
| Image to pin | ghcr.io/umami-software/umami:3.5.0 (tag, linux/amd64 and linux/arm64 manifests checked on the registry) |
| Database | PostgreSQL only (v3 dropped MySQL); the official Compose file uses postgres:15-alpine |
| Licence | MIT (LICENSE at the release tag) |
| Time needed | About 20 minutes (our estimate, not measured) |
| RAM and disk | Not documented by the project; see "Performance and resources" |
| Ports | Umami 3000 (the web app and the tracker); PostgreSQL 5432 stays inside Docker |
| Official docs | umami.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/sendon your Umami address. - New in 3.5.0 and missing from old guides:
APP_SECRETmust be set explicitly, and the default loginadmin/umamimust be replaced at first sign-in. - Platforms: Docker on Linux, Docker Desktop on Windows and Mac. The image has
arm64builds, 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.
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.
| System | What you need |
|---|---|
| Linux | Docker Engine and the Compose plugin; openssl (for secrets). See our Docker on Ubuntu guide. |
| Windows | Docker Desktop (WSL2 backend) and PowerShell. curl.exe ships with Windows 10 and 11. |
| Mac | Docker Desktop (Intel or Apple Silicon) and Terminal. openssl and curl are included. |
Check your tools (the same two commands work in PowerShell):
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 3000on Linux) - [ ] A password manager ready for the admin password and the
.envsecrets - [ ] 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#
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)#
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.
grep -c = ~/docker_volumes/umami/.env
On Windows run (Get-Content .env).Count. Both should print 3.
Tip:
openssl rand -hex 32is the command the official docs give forAPP_SECRETand 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#
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:
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):
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:
{"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=1disables all external calls, and also the website icons, because they come from DuckDuckGo. Remove it if you want icons.DISABLE_TELEMETRY=1andDISABLE_UPDATES=1stop the anonymous telemetry pixel and the version check. You then watch the release page yourself.init: trueand the healthchecks come from the official file.- Compose reads
.envonly to fill the${...}placeholders. The variables reach the app through theenvironment: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:
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:
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):
<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:
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:
'{"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:
docker network create proxy
In the Compose file remove the ports: block of umami and add the networks and labels:
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:
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:
docker network create proxy
mkdir -p ~/docker_volumes/caddy/{conf,data,config}
Save as ~/docker_volumes/caddy/docker-compose.yml:
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:
umami.example.com {
reverse_proxy umami:3000
}
At home with no public domain, use Caddy's own local certificate:
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:
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:
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:
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#
| Control | How |
|---|---|
| Admin password | Change it at first login; add two-factor on the Security page. |
| Web port | 127.0.0.1:3000, or no host port behind a proxy. Never forward 3000 or 5432 on your router. |
| Database | Not 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-up | We found no public sign-up switch in the environment list. Review the user list after setup. |
DISABLE_LOGIN | Disables the login page entirely. It is not single sign-on; do not set it to "harden". |
| Single sign-on | We found no documented OIDC setup in the current docs. Use a proxy-level login if you need one. |
| Docker socket | Umami needs none. Do not mount it. |
Quick tests after each change:
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.
| Mistake | Why it happens | Do this instead |
|---|---|---|
Starting v3.5.0 without APP_SECRET | Older versions fell back to DATABASE_URL; 3.5.0 removed that and rejects empty or placeholder values | Generate 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 umami | The shipped file is an example; latest moves when you pull | Pin 3.5.0, set your own database password |
Keeping admin / umami | Everyone knows it; 3.5.0 forces a change, older installs did not | Change it at first login and add two-factor |
Environment variable not found: DATABASE_URL | A .env file next to Compose only fills ${...} placeholders (issue 449) | Pass every variable in environment: |
localhost in DATABASE_URL inside Docker | The docs' localhost example is for the source install; in a container, localhost is the app itself | Use the service name: @db:5432/umami |
| Using MySQL or old image names | Version 1 and 2 guides use mikecao/umami:mysql-latest and DATABASE_TYPE=mysql (issue 1174); v3 is PostgreSQL only | Use ghcr.io/umami-software/umami and PostgreSQL |
| Jumping versions without reading notes | A 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 /analytics | The docs list it as a build-time setting (discussion 858) | Use a subdomain such as umami.<your-domain> |
| Counting your own visits | The tracker cannot tell you from a visitor | localStorage.setItem('umami.disabled', 1) or IGNORE_IP |
| Script blocked by an ad blocker | Some lists block "analytics" or tracking products by name | See "Ad blockers and the script name" below |
Never backing up .env | APP_SECRET and the two-factor key are not in the database | Back up .env with the dump, and keep both private |
AI assistants: inventing settings such as DISABLE_SIGNUP, NEXTAUTH_URL, HASH_SALT, PUBLIC_URL | These are absent from the current environment list; some are version 1 leftovers | Use 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 HSTS | Delete 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:3000page 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:
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#
| Problem | Solution |
|---|---|
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 fails | Wrong 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 script | Wrong website ID, an ad blocker, or the page cannot reach Umami; open the browser Network tab |
| Mixed content error in the browser console | An https:// site loads http:// Umami; put Umami behind HTTPS |
Blank dashboard, /_next/static/chunks/... return 404 | A proxy or cache serves another build (issue 2716); clear caches, recreate the containers |
| Wrong visitor country or IP | Set TRUSTED_PROXIES as in the HTTPS section |
| Reports slow after a big upgrade | Run ANALYZE; in PostgreSQL (docs); see Updates |
| Cannot reach it from other machines | The 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:
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):
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#
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)#
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:
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-dbshows 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_URLis 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#
- Umami release v3.5.0 (12 November 2026), v3.4.1 and v3.0.0 - read November 2026
- Files at the v3.5.0 tag: docker-compose.yml, package.json, LICENSE, README, app-secret.ts, heartbeat route, telemetry route
- Official docs: installation, updates, environment variables, login, collect data, tracker configuration, bypass ad blockers, exclude my own visits, sending stats, FAQ - read November 2026
- Umami image on GitHub Container Registry (tag 3.5.0, amd64 and arm64 checked), Caddy release v2.11.9 and Caddy docs - November 2026
- GitHub issues and discussions: #449, #858, #1174, #1985, #2014, #2206, #2716, #3115, #4739, #4763
Checked against the official docs on 2026-11-16.