Self-host Umami analytics
Cookie-free web analytics. Your visitors' data stays on your VM.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/umami/prompt.txt | ssh exe.dev new --prompt=/dev/stdinUmami counts pageviews, referrers, countries, devices and custom events without cookies, and keeps every record in your own PostgreSQL database. It's a small Next.js app, so an exe.dev VM suits it well: a real disk for years of history, a dashboard that stays behind exe.dev login, and a public address that answers only the tracker script.
Visitors' browsers need to reach the tracker, so that part is public. The dashboard isn't: it sits on port 3000, which only you and the people you share the VM with can open, and Umami asks for its own password too. Shelley can set it up, back it up, and answer "how did last week go?" from your numbers.
What you get#
- Umami 3 on PostgreSQL, restarted after a reboot.
- A private dashboard on port 3000 and a tracker-only public URL.
- Nightly database backups, with the secrets file beside them.
What's running, and where
https://my-umami.exe.xyz:3000/
The Umami dashboard, behind exe.dev login and Umami's own
https://my-umami.exe.xyz/script.js
The tracker and its collection endpoint, once you make the VM public
Deploy with Shelley#
Click Deploy and Shelley will set up Umami on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe-staging.dev/deploy/umami/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhen it's done, run this on your computer (only you can):
ssh exe.dev share set-public my-umami # lets visitors' browsers reach the trackerWhat Shelley is told
Set up Umami on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/umami.md from top to bottom.
The recipe's example VM name is my-umami. This VM's name is the output of `hostname`: use it wherever the recipe writes my-umami. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- Umami 3 on PostgreSQL, restarted after a reboot.
- A private dashboard on port 3000 and a tracker-only public URL.
- Nightly database backups, with the secrets file beside them.
Read the whole recipe, including closed details, and follow "Install by
hand" first. The opening walkthrough is for the owner afterwards. Do not
run the later Restore or Update instructions.
Work as exedev in ~/umami. Never overwrite an existing ~/umami/.env.
Do not log in to Umami, change its password, or add websites: the owner
does that in the browser. Leave public sharing off; only the owner can
turn it on. Verify docker.service is enabled, all three containers are
restart unless-stopped and healthy or up, localhost:3000/api/heartbeat
answers {"ok":true}, localhost:8000/script.js returns 200, and
localhost:8000/login and localhost:8000/api/websites return 404. Check
the backup timer is enabled and the first dump exists in ~/umami/backups.
Finish with the dashboard URL on port 3000, the default login
(admin / umami, which Umami makes them replace at once), and the command
the owner runs on their own computer to make the tracker public:
ssh exe.dev share set-public my-umami
Finish with the URLs I should open and these commands, which only I can run, from my own computer (with this VM's name in them):
ssh exe.dev share set-public my-umami # lets visitors' browsers reach the tracker
Also at /deploy/umami/prompt.txt. The recipe it follows is /deploy/umami.md.
Sign in and add your site#
Open the dashboard Shelley gives you, https://my-umami.exe.xyz:3000/.
After exe.dev login you'll see Umami's sign-in page.
- Sign in as
adminwith passwordumami. Umami makes you replace that password before you can do anything else. Pick a strong one. - Click Websites → Add website. Name it, enter your site's domain
(
example.com), and Save. - Open the site's Edit page and copy the Tracking code.
The code points at the address you're reading it on, port 3000, which
visitors can't reach. Remove :3000 so it uses the public address:
<script defer src="https://my-umami.exe.xyz/script.js"
data-website-id="your-website-id"></script>
Tip
While you're in Settings, turn on two-factor authentication under Settings → Security. The key that protects it is already in your
.env.
Make the tracker public#
Until now everything on the VM has been private. On your computer:
ssh exe.dev share set-public my-umami
That opens https://my-umami.exe.xyz/, and only that. The
HTTPS proxy keeps port 3000 private, and the tracker proxy
on port 8000 forwards just the tracker script and the endpoint it reports
to. Check from your computer:
curl -sI https://my-umami.exe.xyz/script.js | head -1 # HTTP/2 200
curl -sI https://my-umami.exe.xyz/login | head -1 # HTTP/2 404
Add the script to your site#
Put the tracking code in the <head> of every page, then load a page.
It shows up under Realtime within seconds.
-
Plain HTML or a static site generator: paste it into the shared head template.
-
Next.js (like our Next.js recipe): use
next/scriptinapp/layout.tsx, as Umami's docs advise:import Script from "next/script"; // inside <head> or <body> of the root layout: <Script defer src="https://my-umami.exe.xyz/script.js" data-website-id="your-website-id" /> -
WordPress: add it to your theme's header, or paste it into a header-scripts plugin.
-
Single-page apps need nothing more: Umami follows client-side navigation.
To count a click, add data-umami-event="signup" to the button or link.
To keep your own visits out of the numbers, open your site, then run
localStorage.setItem('umami.disabled', 1) in the browser console.
Nothing showing up? Open the browser's developer tools on your site: the
Network tab should show script.js and a 200 from /api/send. A red
or missing request usually means an ad blocker, or :3000 still in the
script address.
Use your own domain#
A hostname on your own domain, like stats.example.com, looks like part
of your site, and some blocklists match well-known analytics hostnames
and file names. To set one up:
-
At your DNS provider, add
stats.example.com CNAME my-umami.exe.xyz(on Cloudflare, set it to DNS only). -
On your computer:
ssh exe.dev domain add my-umami stats.example.com -
Change the script's address to
https://stats.example.com/script.js.
exe.dev issues the certificate. Keep using
https://my-umami.exe.xyz:3000/ for the dashboard. More in
custom domains.
Rename the tracker, too
Umami can serve its script and endpoint under names of your choosing
(its guide). On the VM, this
uses site.js and /api/site. It adds both to the tracker proxy's
allowlist, and restarts it so it reads the new file:
cd ~/umami
cat >> .env <<'EOF'
TRACKER_SCRIPT_NAME=site.js
COLLECT_API_ENDPOINT=/api/site
EOF
sed -i -e 's#(script|recorder)#(script|recorder|site)#' \
-e 's#(send|record)#(send|record|site)#' tracker.conf
docker compose up -d --wait
docker compose restart tracker
curl -s localhost:8000/site.js | grep -o '/api/site' | head -1
The last line prints /api/site. Change your sites' script to
https://stats.example.com/site.js; the tracking code in Umami now shows
the new name too. The old script.js keeps working, and reports to the
new endpoint.
Share the dashboard#
The dashboard is private to you until you share the VM. On your computer:
ssh exe.dev share add my-umami alice@example.com # one person
ssh exe.dev share add my-umami team # your exe.dev team
They sign in to exe.dev, then to Umami. For a read-only view without a Umami account, open the site's Edit page, add a Share URL, choose what it shows, and send it to them. It's on port 3000, so it still needs exe.dev login: only people you've shared the VM with can open it. To give someone their own Umami login instead, add them under Admin → Users. See sharing.
Ask Shelley about your traffic#
Umami 3.4 added a read-only MCP server for AI assistants. Shelley on the VM can use it without the numbers ever leaving the machine:
- In Umami, open Settings → API keys and create a key.
- Ask Shelley: "Turn on Umami's MCP endpoint and add it as an MCP
server with this API key: …" It adds
MCP_ENABLED=1to~/umami/.env, runsdocker compose up -d, and registershttp://localhost:3000/mcp. - Then ask "Which pages got the most visitors last week?" or "Where did Tuesday's spike come from?"
The endpoint is on port 3000, so it isn't reachable from the internet.
Privacy notes#
Umami is built to need little personal data, but the details matter:
- No cookies. The tracker stores nothing in the browser.
- No IP addresses in the database. Umami uses the visitor's IP
address and browser to make an anonymous session ID, with a salt that
changes each month (
SALT_ROTATIONchanges that), and to look up the country, region and city. Neither the address nor the salt is stored. - No access logs on the public side. The tracker proxy here runs
with
access_log off, so nginx doesn't write visitors' addresses to disk either. - Your data stays on your VM, and Umami keeps it until you delete it (Edit → Reset website, or delete the site).
- Do Not Track: add
data-do-not-track="true"to the script tag to skip visitors whose browser sends it. - Telemetry to Umami's developers is turned off here
(
DISABLE_TELEMETRY=1). The dashboard still loads site icons from DuckDuckGo;PRIVATE_MODE=1in.envstops that.
Whether you need consent for analytics is a legal question about your whole site, not just Umami. Umami's FAQ puts it the same way.
Plausible instead#
Plausible Community Edition is the other popular privacy-friendly choice: a simpler single-page dashboard, AGPL-licensed. It's heavier to run: Plausible, PostgreSQL and ClickHouse, which needs a CPU with SSE 4.2 and, per Plausible, at least 2 GB of RAM. An exe.dev VM handles that. Follow its Compose repository, put its port behind the same kind of tracker-only proxy, and back up both databases. Ask Shelley to set it up if you prefer it; this page sticks to Umami.
Keep your history#
Your data lives in PostgreSQL in ~/umami/postgres. Every night a dump
goes to ~/umami/backups, with a copy of .env. Keep a copy off the
VM too. On your computer:
scp -r my-umami.exe.xyz:umami/backups .
.env holds the secrets that sign logins and protect two-factor
secrets, so treat the backups as private. For updates or problems, ask
Shelley, or open the instructions below.
The nuts and bolts#
These are Shelley's setup steps and your maintenance reference. Tested with Umami 3.5.0, PostgreSQL 18.7 and nginx 1.30 on November 16, 2026.
Install by hand
Create a VM#
On your computer (pick another name if my-umami is taken):
ssh exe.dev new --name=my-umami
ssh my-umami.exe.xyz
The remaining commands run on the VM, as exedev.
Write the secrets#
Three random values: the database password, Umami's APP_SECRET (it
signs logins and is required since 3.5), and the key that encrypts
two-factor secrets. The file is created only once, so running this again
keeps your keys:
sudo systemctl enable --now docker.service
mkdir -p ~/umami && cd ~/umami
if [ ! -f .env ]; then
(umask 077; cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
DISABLE_TELEMETRY=1
EOF
)
fi
ls -l .env
ls shows -rw-------. Enabling docker.service makes the containers
come back after a reboot.
Start Umami#
cd ~/umami
cat > compose.yaml <<'EOF'
name: umami
services:
db:
image: postgres:18
restart: unless-stopped
environment:
POSTGRES_DB: umami
POSTGRES_USER: umami
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes: ["./postgres:/var/lib/postgresql"]
healthcheck:
test: ["CMD-SHELL", "pg_isready -U umami -d umami"]
interval: 5s
retries: 20
umami:
image: ghcr.io/umami-software/umami:3
restart: unless-stopped
init: true
env_file: .env
environment:
DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
CLIENT_IP_HEADER: x-real-ip
ports: ["3000:3000"]
depends_on:
db: { condition: service_healthy }
healthcheck:
test: ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat"]
interval: 10s
retries: 30
tracker:
image: nginx:stable-alpine
restart: unless-stopped
ports: ["8000:8000"]
volumes: ["./tracker.conf:/etc/nginx/conf.d/default.conf:ro"]
depends_on: [umami]
EOF
cat > tracker.conf <<'EOF'
server {
listen 8000;
access_log off;
resolver 127.0.0.11 valid=30s;
set $umami http://umami:3000;
# exe.dev's proxy puts the visitor's address last in X-Forwarded-For.
set_real_ip_from 0.0.0.0/0;
set_real_ip_from ::/0;
real_ip_header X-Forwarded-For;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
# The tracker and what it talks to; nothing else of Umami is public.
location ~ ^/(script|recorder)\.js$ {
limit_except GET { deny all; }
proxy_pass $umami;
}
location ~ ^/api/(send|record)$ {
limit_except POST OPTIONS { deny all; }
proxy_pass $umami;
}
location ~ ^/api/websites/[0-9a-f-]+/recorder$ {
limit_except GET OPTIONS { deny all; }
proxy_pass $umami;
}
location ~ ^/[pq]/[^/]+$ {
limit_except GET { deny all; }
proxy_pass $umami;
}
location = / {
default_type text/plain;
return 200 "Umami tracker. The dashboard is private.\n";
}
location / { return 404; }
}
EOF
docker compose up -d --wait --wait-timeout 300
docker compose ps
curl -fsS localhost:3000/api/heartbeat; echo
curl -s -o /dev/null -w 'tracker %{http_code}\n' localhost:8000/script.js
curl -s -o /dev/null -w 'login on the public port %{http_code}\n' localhost:8000/login
printf 'Dashboard: https://%s.exe.xyz:3000/\n' "$(hostname)"
All three services are up, db and umami healthy; the checks print
{"ok":true}, tracker 200 and login on the public port 404. On first
start Umami creates its tables and the admin / umami account.
What the pieces do:
- The HTTPS proxy sends
https://my-umami.exe.xyz/to port 8000 and:3000to Umami. Port 3000 always needs exe.dev login. - The tracker proxy on 8000 forwards only the tracker script, the collection endpoint, and the session-replay recorder and pixels and links if you use them. Everything else, the login page and API included, is a 404.
- It takes the visitor's address from the end of
X-Forwarded-For, which exe.dev's proxy sets, and passes only that to Umami (CLIENT_IP_HEADER), so a browser can't claim to be somewhere else.
Set up nightly backups#
pg_dump copies the database while Umami keeps counting. The script
checks each dump is readable and keeps two weeks:
cd ~/umami
cat > backup.sh <<'EOF'
#!/bin/sh
set -eu
umask 077
cd "$(dirname "$0")"
mkdir -p backups
out="backups/umami-$(date +%Y%m%d-%H%M%S).dump"
docker compose exec -T db pg_dump -U umami -d umami -Fc > "$out.tmp"
docker compose exec -T db pg_restore --list < "$out.tmp" > /dev/null
mv "$out.tmp" "$out"
cp .env backups/umami.env
find backups -name 'umami-*.dump' -mtime +14 -delete
EOF
chmod +x backup.sh
sudo tee /etc/systemd/system/umami-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up Umami
After=docker.service
[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/umami/backup.sh
EOF
sudo tee /etc/systemd/system/umami-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Umami nightly
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now umami-backup.timer
sudo systemctl start umami-backup.service
systemctl list-timers umami-backup.timer
ls -l backups
The timer lists its next run, and backups holds a .dump and
umami.env. Now open the dashboard and follow the walkthrough at the top.
Back up and restore
For an extra backup, on the VM: ~/umami/backup.sh.
Restore#
On a new VM, first put the old umami.env in place as ~/umami/.env
(mkdir -p ~/umami, then copy it there with scp), and copy a dump into
~/umami/backups/. Then run Install by hand, which keeps that .env.
With the same APP_SECRET and two-factor key, logins and two-factor
settings carry over.
On the VM, substitute your dump's filename:
cd ~/umami
backup=backups/umami-YYYYMMDD-HHMMSS.dump
sudo systemctl stop umami-backup.timer
docker compose stop umami tracker
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists --no-owner < "$backup"
docker compose up -d --wait
sudo systemctl start umami-backup.timer
pg_restore replaces every table with the backup's. Sign in with the
password you had when the backup was taken; your sites and their
history are back.
Update
On the VM, back up, then pull and restart:
cd ~/umami
./backup.sh && docker compose pull && docker compose up -d --wait
docker compose exec -T umami node -e 'console.log(require("./package.json").version)'
The last line prints the running version. Umami applies its database
migrations when it starts. The 3 tag keeps you on Umami 3; read the
release notes before
a new major version, and after one run
docker compose exec -T db psql -U umami -d umami -c 'ANALYZE;', as
Umami advises, so dashboards stay fast.
postgres:18 stays on PostgreSQL 18. Moving to a later major version
means a dump and restore into a fresh data directory; ask Shelley when
the time comes.
Troubleshooting
Start with the logs, on the VM:
cd ~/umami
docker compose ps
docker compose logs umami --tail=50
- No visits recorded? Check the script address has no
:3000, the VM is public (ssh exe.dev share show my-umamion your computer), and the browser's Network tab shows/api/sendreturning 200. Requests fromcurland other bots are dropped on purpose; test with a browser. - Visits from you only? Ad blockers block some visitors. Use your own domain and rename the tracker, above.
umamirestarting, withAPP_SECRETin the log?.envlost it. Restore.envfrombackups/umami.env.- Down after a reboot? Run
sudo systemctl enable --now docker.service. - Forgot the Umami password? Ask Shelley to reset it in the database, or restore a backup taken when you knew it.
Frequently asked questions#
Is Umami free?
Yes. Umami is open source under the MIT license, with no limits on sites or pageviews when you host it. You pay for the VM; see exe.dev plans.
Does Umami use cookies? Do I need a cookie banner?
Umami's tracker sets no cookies and Umami doesn't store IP addresses. Whether your site needs a banner depends on everything else on it and the law where you and your visitors are; Umami's own FAQ says the same.
Can Umami use MySQL or SQLite?
No. Umami 3 supports PostgreSQL only (12.14 or newer); MySQL support ended with v3, and SQLite was never supported. Umami has a migration guide for v2 MySQL installs.
How many sites can one VM track?
As many as you add. In our test the whole stack used about 220 MB of memory at rest; PostgreSQL grows with your pageviews, and you can grow the disk later with ssh exe.dev resize my-umami --disk=50GB.
Umami or Plausible Community Edition?
Both are privacy-friendly and run well on a VM. Umami needs only PostgreSQL. Plausible CE (AGPL) also runs ClickHouse, wants at least 2 GB of RAM, and ships as its own Compose project. See Plausible instead.
Can my teammates see the stats?
Yes. Share the VM with them and they reach the dashboard after exe.dev login. Give them a Umami account, or a Umami Share URL that needs no account; see Share the dashboard.
Updated Nov 16, 2026 · tested end to end Nov 16, 2026 · Markdown · manifest.json · Something wrong? Tell us