Self-host Umami on a managed VPS: your web analytics on your own server

What Umami does

Umami is an open-source web and product analytics platform. Its documentation describes a tool that brings traffic, campaigns, visitor behavior, conversions, retention and revenue together, from the first visit to the outcomes that matter to your business. It is written in TypeScript on Next.js, and its Docker image runs under an unprivileged account.

• Acquisition: pageviews, visitors, referrers, countries, devices and real-time activity, with UTM campaigns, short links and tracking pixels.
• Behavior: custom events, journeys, session replays, heatmaps, segments, cohorts and retention.
• Conversion: goals, funnels, attribution and revenue tracking by page and by campaign.
• Sharing: boards, teams, a public share URL, an API and a read-only MCP server for your AI assistant.
• Modern sites: the FAQ states that Umami tracks page navigation in single-page applications on its own, with no extra setting.

One instance tracks several websites: each one gets its own ID and tracking script, and your colleagues find their way around through accounts and teams.

What the MIT license allows

Umami is published under the MIT license, in the name of Umami Software, Inc. It grants, free of charge, the right to use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software. You can therefore run it for your business and for your clients’ websites, with no license to buy.

Its only condition: the copyright notice and the permission notice go with all copies or substantial portions of the software. Like any MIT license, it provides the software “as is”, without warranty.

Cookies and personal data: what the project says

The documentation presents Umami as analytics without cookies, without cross-site tracking and without the automatic collection of personal data. Self-hosted, it keeps your analytics on your own server: you decide where they live and how long they stay.

Three tracking script settings go further, if you wish: data-exclude-search removes search parameters from the recorded URLs, data-exclude-hash removes the hash, and data-do-not-track turns tracking off for browsers that expose the Do Not Track preference. The documentation notes that this last setting is not, on its own, a complete consent management solution.

If you identify logged-in visitors with data-distinct-id or umami.identify(), the documentation recommends an internal user ID or a hash rather than an email address: the value can be read in the page’s HTML.

Installing with Docker Compose and PostgreSQL

The repository ships a docker-compose.yml that starts Umami and its PostgreSQL database. Since version 3, PostgreSQL is the only supported database, version 12.14 at minimum, and the documentation recommends setting it to the UTC timezone. On a server with Docker installed, create a folder and start with its secrets, generated at random with openssl, as the documentation suggests:

cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 24)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

Then place this compose.yaml next to it. It follows the project’s file at version 3.4.1, with two changes: the secrets come from the .env file, and the port is published on 127.0.0.1 only.

services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

docker compose up -d
curl -s http://127.0.0.1:3000/api/heartbeat

• DATABASE_URL: the only required variable, the connection string for the database. The hexadecimal password goes in as it is; a password with special characters would need percent-encoding.
• APP_SECRET: a random string that secures authentication tokens, unique to each installation. In the code of version 3.4.1, it also goes into the computation of session IDs: keep it stable.
• TWO_FACTOR_ENCRYPTION_KEY: 64 hexadecimal characters that encrypt two-factor authentication secrets. Without it, nobody can enable two-factor authentication.
• On startup, the container checks the database connection and version, then applies the schema migrations itself. On the first run, it creates the tables and the admin account. The /api/heartbeat probe answers {"ok":true} once Umami is ready.
• The latest tag follows the latest published release. The project’s registry also publishes version tags, such as 3.4.1, to pin the one you run.

The installation documentation gives no figure for memory or CPU. The size depends on the traffic of the tracked websites and on the volume of data you keep. On a managed VPS, tell us about your usage and we recommend the right size.

HTTPS: the reverse proxy

Umami listens over HTTP on port 3000, and the documentation suggests serving it behind your web server, through a reverse proxy. Give it its own subdomain, such as stats.example.com, pointed at the server with A and AAAA records. Serving Umami under a path goes through BASE_PATH, a variable read when the application is built: with the published image, the subdomain is the direct route.

The proxy must also pass on the visitor’s address. Umami reads it from the headers it receives, including X-Real-IP and X-Forwarded-For: it uses it to tell visitors apart and to locate their country. If your proxy uses another header, CLIENT_IP_HEADER names it.

With Caddy

Caddy obtains the Let’s Encrypt certificate and enables HTTPS by itself. Its reverse_proxy directive sets X-Forwarded-For by default: these three lines are all you need.

stats.example.com {
  reverse_proxy 127.0.0.1:3000
}

With Nginx and Certbot

This block follows the Nginx example from the Umami documentation, listening on port 80 so that Certbot can set up HTTPS:

server {
  listen 80;
  listen [::]:80;
  server_name stats.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Certbot then installs the certificate and takes care of renewing it:

sudo certbot --nginx

The first login: the admin account and two-factor authentication

When it creates its database, Umami opens an administrator account: username admin, password umami. The documentation asks you to change this password at your first login.

1. Open your HTTPS address and log in with admin and umami.
2. Open Settings from the profile button in the sidebar, then Profile, and click Change password.
3. In the Security tab, enable two-factor authentication: scan the QR code with your authenticator app, enter the six-digit code, then store the ten backup codes somewhere safe, as they are shown only once.

• Requiring two-factor authentication: an admin can require it for the whole instance, for one user or for one team, from the admin pages.
• Attempts: five wrong codes lock further attempts for 15 minutes.
• Your team’s accounts: the admin pages manage the users, websites and teams of the whole instance.

Keep TWO_FACTOR_ENCRYPTION_KEY with your backups: the documentation warns that losing or changing this key makes stored secrets unreadable, and each user must then enroll in two-factor authentication again.

Adding a website and its tracking script

1. In Websites, click Add website.
2. Give the website a name, then its domain: Umami uses it to filter your own pages out of the referrers list.
3. Open Edit on that website and copy the code from the Tracking code section.
4. Paste it into the <head> of your pages, then visit your website: data appears in the dashboard right away.

<script defer src="https://stats.example.com/script.js" data-website-id="your-website-id"></script>

• Nothing showing up? The documentation suggests the network tab of the browser developer tools: requests to your instance should go out without errors.
• Next.js: add the code with the next/script component rather than a plain <script> tag.
• data-domains limits tracking to your production domains, which keeps your test environments out of the statistics.
• Your own visits are excluded website by website, from the browser console, with localStorage.setItem('umami.disabled', 1).

A script name of your own

Some ad blockers block anything that looks like analytics. Self-hosted, Umami is already served from your own domain, and two variables go further: TRACKER_SCRIPT_NAME gives the script another name than script.js, and COLLECT_API_ENDPOINT renames the collection endpoint, instead of /api/send. The script then calls the new endpoint by itself; only the source of the tracking code changes on your pages.

TRACKER_SCRIPT_NAME: "stats.js"
COLLECT_API_ENDPOINT: "/api/collect"

Useful settings

These environment variables go into the umami service of compose.yaml, then docker compose up -d recreates the container to pick them up:

Backups

Everything Umami keeps lives in its PostgreSQL database: accounts, websites, teams and analytics. Dump it every day and right before each update: self-hosted, this data is kept with no time limit. Next to the database, the .env file holds the secrets that make it usable:

Dumping the database while it runs

pg_dump makes a consistent dump while the database is in use. The custom format, -Fc, is compressed and restores with pg_restore:

docker compose exec -T db pg_dump -U umami -d umami -Fc > umami-$(date +%F).dump

Schedule this command on the server at least once a day, prune the dumps, which pile up, and send a copy elsewhere. Kept on the server’s disk, these dumps are also part of its nightly backups.

Restoring

1. Stop Umami, leaving the database running: docker compose stop umami.
2. Restore the dump into the database, replacing existing objects.
3. Start Umami again, then check that your websites and their analytics are there.

docker compose stop umami
docker compose exec -T db pg_restore -U umami -d umami --clean --if-exists < umami-YYYY-MM-DD.dump
docker compose start umami

Repeat this drill from time to time, on a copy: that is how you check that a backup works.

Updates

The documentation gives two commands, from the compose.yaml folder. The database stays in its volume:

docker compose pull
docker compose up --force-recreate -d

On restart, the container applies the schema migrations by itself. Version 3.4.0, of 17 September 2026, carried two of them, for annotations and API keys; version 3.4.1, of 23 October 2026, carries none. After a major upgrade, such as the move to version 3, the documentation suggests running ANALYZE in PostgreSQL so that dashboards get their speed back:

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

• The release notes say what each version changes. Version 3.4.1 is a security hotfix that updates Next.js and the Node.js base image; its notes ask every self-hosted instance to upgrade by pulling the image again.
• From a version 2 on MySQL: version 3 no longer supports MySQL. The project’s migration guide moves the data to PostgreSQL on version 2.19.0, before the upgrade to version 3.
• PostgreSQL itself: keep the file’s postgres:15-alpine tag. Moving to a new major PostgreSQL version takes a dump and restore, or pg_upgrade.

Who does what on a managed VPS

Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Umami remains your software, with its settings and its data.

If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.