---
title: "Self-host Umami analytics"
description: "Run Umami web analytics on exe.dev with PostgreSQL: a public tracker on your own domain, a private dashboard behind exe.dev login, nightly backups."
url: https://exe-staging.dev/deploy/umami
category: "Monitoring"
updated: 2026-11-16
---

# Self-host Umami analytics

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

- **Software:** Umami (https://umami.is)
- **Source:** https://github.com/umami-software/umami
- **License:** MIT
- **Time:** 10 minutes
- **Example VM name:** `my-umami` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/umami/manifest.json

## 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.

Running on the VM:

- **Umami 3**: ghcr.io/umami-software/umami:3, dashboard and API, port 3000
- **PostgreSQL 18**: postgres:18; all your analytics data, data in `~/umami/postgres`
- **Tracker proxy**: nginx; the tracker script and its endpoint, nothing else, port 8000
- **Nightly backup**: pg_dump from a systemd timer; keeps two weeks, data in `~/umami/backups`

How it is reached:

- https://my-umami.exe.xyz:3000/ (private): The Umami dashboard, behind exe.dev login and Umami's own
- https://my-umami.exe.xyz/script.js (public): The tracker and its collection endpoint, once you make the VM public

## Deploy with Shelley

Open https://exe-staging.dev/new?prompt=Set%20up%20Umami%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fumami.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-umami.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-umami.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20Umami%203%20on%20PostgreSQL%2C%20restarted%20after%20a%20reboot.%0A-%20A%20private%20dashboard%20on%20port%203000%20and%20a%20tracker-only%20public%20URL.%0A-%20Nightly%20database%20backups%2C%20with%20the%20secrets%20file%20beside%20them.%0A%0ARead%20the%20whole%20recipe%2C%20including%20closed%20details%2C%20and%20follow%20%22Install%20by%0Ahand%22%20first.%20The%20opening%20walkthrough%20is%20for%20the%20owner%20afterwards.%20Do%20not%0Arun%20the%20later%20Restore%20or%20Update%20instructions.%0AWork%20as%20exedev%20in%20~%2Fumami.%20Never%20overwrite%20an%20existing%20~%2Fumami%2F.env.%0ADo%20not%20log%20in%20to%20Umami%2C%20change%20its%20password%2C%20or%20add%20websites%3A%20the%20owner%0Adoes%20that%20in%20the%20browser.%20Leave%20public%20sharing%20off%3B%20only%20the%20owner%20can%0Aturn%20it%20on.%20Verify%20docker.service%20is%20enabled%2C%20all%20three%20containers%20are%0Arestart%20unless-stopped%20and%20healthy%20or%20up%2C%20localhost%3A3000%2Fapi%2Fheartbeat%0Aanswers%20%7B%22ok%22%3Atrue%7D%2C%20localhost%3A8000%2Fscript.js%20returns%20200%2C%20and%0Alocalhost%3A8000%2Flogin%20and%20localhost%3A8000%2Fapi%2Fwebsites%20return%20404.%20Check%0Athe%20backup%20timer%20is%20enabled%20and%20the%20first%20dump%20exists%20in%20~%2Fumami%2Fbackups.%0AFinish%20with%20the%20dashboard%20URL%20on%20port%203000%2C%20the%20default%20login%0A%28admin%20%2F%20umami%2C%20which%20Umami%20makes%20them%20replace%20at%20once%29%2C%20and%20the%20command%0Athe%20owner%20runs%20on%20their%20own%20computer%20to%20make%20the%20tracker%20public%3A%0Assh%20exe.dev%20share%20set-public%20my-umami%0A%0AFinish%20with%20the%20URLs%20I%20should%20open%20and%20these%20commands%2C%20which%20only%20I%20can%20run%2C%20from%20my%20own%20computer%20%28with%20this%20VM%27s%20name%20in%20them%29%3A%0A%20%20ssh%20exe.dev%20share%20set-public%20my-umami%20%20%20%23%20lets%20visitors%27%20browsers%20reach%20the%20tracker%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/umami/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Then, on your own computer:

```sh
ssh exe.dev share set-public my-umami   # lets visitors' browsers reach the tracker
```

Or follow the steps below by hand.

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](/docs/sharing) 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.

## 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:

```html
<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:

```bash
ssh exe.dev share set-public my-umami
```

That opens `https://my-umami.exe.xyz/`, and only that. The
[HTTPS proxy](/docs/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:

```bash
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](/deploy/nextjs)): use
  `next/script` in `app/layout.tsx`, as Umami's docs advise:

  ```tsx
  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:

   ```bash
   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](/docs/cnames).

<details id="rename-the-tracker" class="dp-details">
<summary>Rename the tracker, too</summary>

Umami can serve its script and endpoint under names of your choosing
([its guide](https://umami.is/docs/bypass-ad-blockers)). 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:

```bash
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.

</details>

## Share the dashboard

The dashboard is private to you until you share the VM. On your computer:

```bash
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](/docs/sharing).

## Ask Shelley about your traffic

Umami 3.4 added a read-only [MCP server](https://github.com/umami-software/umami/blob/master/packages/mcp/README.md)
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](https://umami.is/docs/faq) puts
it the same way.

## Plausible instead

[Plausible Community Edition](https://github.com/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:

```bash
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.

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Install by hand</summary>

### Create a VM

On your computer (pick another name if `my-umami` is taken):

```bash
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:

```bash
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

```bash
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](/docs/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](https://umami.is/docs/pixels) 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:

```bash
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.

</details>

<details id="back-up-and-restore" class="dp-details">
<summary>Back up and restore</summary>

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:

```bash
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.

</details>

<details id="update" class="dp-details">
<summary>Update</summary>

On the VM, back up, then pull and restart:

```bash
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](https://github.com/umami-software/umami/releases) before
a new major version, and after one run
`docker compose exec -T db psql -U umami -d umami -c 'ANALYZE;'`, as
[Umami advises](https://umami.is/docs/updates), 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.

</details>

<details id="troubleshooting" class="dp-details">
<summary>Troubleshooting</summary>

Start with the logs, on the VM:

```bash
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.

</details>

## 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](https://exe.dev/pricing).

### 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](https://umami.is/docs/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](https://umami.is/docs/guides/migrate-mysql-postgresql) 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](https://github.com/plausible/community-edition) (AGPL) also runs ClickHouse, wants at least 2 GB of RAM, and ships as its own Compose project. See [Plausible instead](#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](#share-the-dashboard).


## Related

- [Self-host Uptime Kuma](https://exe-staging.dev/deploy/uptime-kuma.md): A little lookout for your websites. Green bars encouraged.
- [Self-host PostgreSQL](https://exe-staging.dev/deploy/postgres.md): Your own Postgres on a real disk, with backups you've actually restored.
- [Deploy Next.js on your own server](https://exe-staging.dev/deploy/nextjs.md): Your Next.js app on a server of its own. git push to deploy.
- [Deploy a Docker Compose app from GitHub](https://exe-staging.dev/deploy/docker-compose.md): Your compose.yaml on a VM of its own. git push to deploy.
- [Self-host n8n](https://exe-staging.dev/deploy/n8n-2.md): Connect your apps. Let the boring bits run themselves.
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
