Skip to content

Self-host Umami analytics

Cookie-free web analytics. Your visitors' data stays on your VM.

Deploy on exe.dev

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/stdin

Umami 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
Private https://my-umami.exe.xyz:3000/ The Umami dashboard, behind exe.dev login and Umami's own
Public https://my-umami.exe.xyz/script.js The tracker and its collection endpoint, once you make the VM public
my-umami.exe.xyz exe.dev VM
Umami 3 ghcr.io/umami-software/umami:3, dashboard and API :3000
PostgreSQL 18 postgres:18; all your analytics data ~/umami/postgres
Tracker proxy nginx; the tracker script and its endpoint, nothing else :8000
Nightly backup pg_dump from a systemd timer; keeps two weeks ~/umami/backups

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/stdin

When it's done, run this on your computer (only you can):

ssh exe.dev share set-public my-umami   # lets visitors' browsers reach the tracker
What 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.

  1. Sign in as admin with password umami. Umami makes you replace that password before you can do anything else. Pick a strong one.
  2. Click Websites → Add website. Name it, enter your site's domain (example.com), and Save.
  3. 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/script in app/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:

  1. At your DNS provider, add stats.example.com CNAME my-umami.exe.xyz (on Cloudflare, set it to DNS only).

  2. On your computer:

    ssh exe.dev domain add my-umami stats.example.com
    
  3. 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:

  1. In Umami, open Settings → API keys and create a key.
  2. Ask Shelley: "Turn on Umami's MCP endpoint and add it as an MCP server with this API key: …" It adds MCP_ENABLED=1 to ~/umami/.env, runs docker compose up -d, and registers http://localhost:3000/mcp.
  3. 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_ROTATION changes 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=1 in .env stops 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 :3000 to 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-umami on your computer), and the browser's Network tab shows /api/send returning 200. Requests from curl and 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.
  • umami restarting, with APP_SECRET in the log? .env lost it. Restore .env from backups/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