How to Use Umami: The Beginner's Guide (First Docker Run, the Admin-Password Rule, First Website, and the Ad-Blocker Trick)

CodexFuse Team · 2026-10-31T13:54:19.281Z · 14 min read

Learn how to use Umami: the first Docker run, the admin-password rule, your first website, the tracking code, HTTPS with Caddy, and the ad-blocker rename trick.

How to Use Umami: The Beginner's Guide (First Docker Run, the Admin-Password Rule, First Website, and the Ad-Blocker Trick)

Learning how to use Umami is the simplest route to self-hosted web analytics. Umami is an open-source, privacy-focused alternative to Google Analytics — MIT-licensed, built in Node.js, and small enough to run on a modest server: the project holds roughly 39,800 GitHub stars (per the live repository data fetched today), and the current release is v3.4.1, published on GitHub on October 23, 2026. This Umami tutorial runs the complete first arc in one sitting: your first Docker run, the admin-password rule every beginner must follow, adding your first website, installing the tracking code, verifying your first page views, putting the whole thing behind HTTPS, and the ad-blocker rename trick that keeps your own script loading. If Docker is new to you, our Docker beginner guide walks through the container step this guide builds on. You keep your visitors' data on your own server — no Google account, no cookies, no third party.

What is Umami?

Umami is a simple, fast, privacy-focused web analytics platform you self-host on your own infrastructure. Instead of routing visitor data through Google's servers, you run Umami in a Docker container backed by a PostgreSQL database, paste a tiny tracking script into your site's <head>, and read page views, referrers, devices, countries, events, and campaign data in your own dashboard. It collects no personal data by default and uses no cookies, which is what makes it a straightforward choice for GDPR-minded site owners. You can also use the paid Umami Cloud instead of self-hosting, but this guide covers the self-hosted route — the one where your data never leaves your server.

How do you use Umami? The 7-step first arc

Before the terminal, here is the whole arc so you can see where you are heading:

1. Check the requirements — the PostgreSQL rule comes first, not last.
2. Run Umami with Docker Compose, with real secrets and a pinned image tag.
3. Follow the admin-password rule: log in once, change the default credentials immediately.
4. Add your first website in the dashboard.
5. Paste the tracking code into your site's <head>.
6. Verify your first data lands in the dashboard.
7. Apply the ad-blocker rename trick so your tracker script survives content blockers.

Step 1: What do you need before you install Umami?

Umami's requirements are modest, but two of them trip up beginners — and one is a hard rule, not a preference. The official self-hosting documentation lists Node.js 18.18 or higher, PostgreSQL 12.14 or higher (or ClickHouse for high-volume deployments), and a Linux, macOS, or Windows server with at least 1 GB of RAM; for production the docs recommend 2 GB of RAM and 20 GB of disk space.

The hard rule: Umami v3 does not run on MySQL. The project maintainer, Mike Cao, confirmed this directly in issue #3859 after a user tried it — v3 requires PostgreSQL. Older tutorials (the v1/v2 era) describe MySQL support, and following them with a v3 image is a dead end. Choose PostgreSQL from the start. You will run it as a second container next to the app, and Umami's Docker setup wires the two together for you. The server itself can be the smallest VPS that meets the RAM requirement — our guide on what is VPS hosting covers picking the box this stack runs on. A current-generation Debian or Ubuntu install with Docker installed is all the tooling you need.

Step 2: How do you run Umami with Docker for the first time?

Docker is the recommended deployment, and the official route is a single docker compose up -d from the cloned repository — but the stock compose file uses placeholder secrets, and a current beginner guide from October 2026 (13 days ago) shows a safer first-run shape: real secrets in a .env file, a pinned image tag, and the database password chosen once and kept forever. Here is that shape:

# .env — create real values, never use placeholders
POSTGRES_PASSWORD=a-long-random-password-you-save-in-a-password-manager
APP_SECRET=another-long-random-secret
TWO_FACTOR_ENCRYPTION_KEY=openssl rand -hex 32  # run this command to generate one

# docker-compose.yml
services:
  umami:
    image: ghcr.io/umami-software/umami:3.4.1
    container_name: umami
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
      TRACKER_SCRIPT_NAME: analytics.js
      COLLECT_API_ENDPOINT: /api/track
    ports:
      - "127.0.0.1:3000:3000"
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: postgres:15.19-alpine
    container_name: umami-db
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U umami"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
volumes:
  umami-db:

Four deliberate choices are baked into that file. First, the image tag is pinned to 3.4.1 — the current release as of this writing — never :latest, so a future major release cannot surprise you. Second, APP_SECRET and TWO_FACTOR_ENCRYPTION_KEY are set explicitly in the environment; Umami v3 expects both for session and two-factor handling. Third, the PostgreSQL password is chosen once and kept: the October 2026 deployment guide warns that changing it later breaks the app's authentication against the database (you will meet a 28P01 error if you try). Fourth, the app binds to 127.0.0.1:3000 — localhost only — because a reverse proxy takes the public side in Step 8, and nothing should talk to the analytics app directly. The two rename variables (TRACKER_SCRIPT_NAME and COLLECT_API_ENDPOINT) are the ad-blocker trick from Step 7, set at first boot so nothing has to change later.

Start it with docker compose up -d. The app container waits for a healthy database, initializes the schema, and starts Umami on port 3000.

Step 3: What is the admin-password rule?

The admin-password rule is this: Umami ships with a default admin account — username admin, password umami — and the official documentation states you must change these credentials immediately after your first login. This is not optional hygiene. Analytics dashboards are exactly the kind of exposed admin panel that gets probed, and the default credentials are public knowledge.

With the localhost binding from Step 2, open http://localhost:3000 on the server itself (or tunnel it with ssh -L 3000:127.0.0.1:3000 you@server and open it on your laptop), log in with admin / umami, and change the password before doing anything else — the dashboard path is Settings, then Profile. Do not add your website or share the URL first; the first session after install is the most dangerous one.

Step 4: How do you add your first website?

In the dashboard, go to Websites and click Add website. The form asks for two things: a name and a domain. The name can be anything — it is just a label in your dashboard — but the domain should be the actual website domain you want to track. Umami uses the domain to associate collected data with the right website record, so spelling it exactly right (including www vs non-www if it matters for your site) keeps your own test visits and the real traffic in the right place. Save it, then open the website's edit screen: this is where Umami shows you the tracking code for this specific site.

Step 5: How do you install the Umami tracking code?

The tracking code is a small snippet Umami generates per website, built around a website ID. Paste it into the <head> section of every page you want to track:

<script defer src="https://stats.example.com/analytics.js" data-website-id="YOUR-WEBSITE-ID"></script>

Two details matter. The defer attribute means the script loads after the page renders — analytics must never slow down the first paint. The data-website-id is what ties hits to the website record you created in Step 4; copy it from the edit screen, do not type it from memory. (The default script name is script.js — this example shows analytics.js because we renamed it in Step 2 for the ad-blocker trick; the data attribute is the same either way.)

Step 6: How do you verify your first page view?

Visit your website, then return to the Umami dashboard and look at the realtime view — your visit should appear within seconds. If no data appears, the troubleshooting sequence from a current VPS deployment guide is exact: open your browser's developer tools, check whether the tracker script request reaches your stats hostname, then check whether /api/track requests (the renamed collect endpoint) go out. The two usual culprits are a browser content blocker eating the script request, or a wrong data-website-id. Extensions like ad blockers can block analytics scripts even when they are self-hosted — which is exactly why Step 7 exists.

Step 7: What is the ad-blocker trick for Umami?

The ad-blocker trick is renaming Umami's tracker script and collect endpoint away from the defaults that filter lists match. Content blockers ship with filter rules that recognize common analytics file names and endpoints — the default script.js is one of them. Umami supports two environment variables for this: TRACKER_SCRIPT_NAME, which renames the served tracker script (we set analytics.js in Step 2), and COLLECT_API_ENDPOINT, which renames the endpoint the script reports to (we set /api/track).

Set both on your own hostname — stats.example.com in this guide's examples — so neither the script URL nor the collect URL matches the obvious block rules. Be honest about what this buys you: it reduces casual blocking by filter lists that match the default names, but it does not make tracking invisible. A determined user with an aggressive list or a custom rule can still block it. The honest posture is the documented one: you renamed the defaults so ordinary visitors' page views are counted, not so you can track people against their will.

How do you put Umami behind HTTPS?

Umami on its own serves plain HTTP on port 3000, so the public hostname must sit behind a reverse proxy that terminates TLS. Caddy is the fastest route here: it fetches certificates automatically and its config for a single service is a few lines. Point your stats hostname's DNS at the server, then use this Caddyfile — our Caddy beginner guide explains each line if reverse proxies are new:

stats.example.com {
    reverse_proxy 127.0.0.1:3000
}

Because the compose file already binds Umami to 127.0.0.1:3000, the proxy is the only public door — the app itself never faces the internet. After Caddy comes up with a valid certificate, log in through the public hostname and confirm the dashboard works over HTTPS before sharing it.

Umami vs Matomo: which should you pick?

Umami and Matomo are the two names that come up for self-hosted analytics, and they are different lanes, not rivals. Matomo is the heavier, full-featured sibling — PHP and MySQL, deep reporting, goals, funnels, heatmaps — while Umami is the lightest option: Node.js, PostgreSQL, a small focused dashboard, and barely any resource appetite. This guide's cluster covers both because the choice is the question most beginners actually ask first. Here is the decision as it stands in 2026:

The rule of thumb: if your question is "how many people read my site and where did they come from," Umami is the answer and this guide is the whole arc. If you need goal conversion funnels, campaign attribution, and heatmaps, read our Matomo beginner guide instead — it covers the heavier install and the first report on the same beginner footing.

Why leave Google Analytics for Umami?

The case for self-hosted analytics is not ideological — it is practical. Google Analytics 4 loads a heavier script, sets cookies, and sends your visitors' data to Google's servers, which means consent banners, data-processing agreements, and privacy policies with real legal weight behind them. Umami collects no personal data by default and uses no cookies, which collapses the consent question to something a small site can actually answer. Your data also lives in your own PostgreSQL database, under your own backup policy — the qde.com deployment guide phrases it well: traffic records land on your server, not in someone else's ad product. There is no sampling, no retention limit imposed by a vendor, and no account that can be throttled. The cost of that independence is the maintenance this guide's last section covers.

How do you back up and update Umami?

The two maintenance jobs people forget are backups and updates. Your analytics data lives entirely in the PostgreSQL container's volume, so backing up means dumping that database — a cron job like docker exec umami-db pg_dump -U umami umami > /backups/umami-$(date +%F).sql is the whole job, and you should test restoring it at least once before you depend on it. Updating is docker compose pull followed by docker compose up -d; Umami's build step runs the database migrations for you, so the app and schema move together. Because you pinned the image tag in Step 2, updates are a deliberate decision, not a surprise — check the release notes (v3.4.1 is current at this writing) before bumping the tag. And since this is infrastructure you now own, pair it with outside-in monitoring — our website uptime monitor watches the stats hostname so you learn about outages from an alert, not from a week of missing data.

What mistakes do Umami beginners make?

Sources

• GitHub — umami-software/umami repository data and releases API, fetched 2026-10-31: v3.4.1 released October 23, 2026; ~39,800 stars; MIT license.
• Umami self-hosting documentation (crawled 2026-10-27): Node.js 18.18+ requirement, PostgreSQL 12.14+ or ClickHouse, 1 GB RAM minimum (2 GB recommended for production), Docker as the recommended deployment, docker compose up -d quick start, port 3000, default admin / umami credentials with the change-immediately rule, DATABASE_URL format, automatic schema initialization and default admin creation on build.
• dev.to/deploylark — "How to Self-Host Umami Analytics with Docker and PostgreSQL" (published ~13 days before 2026-10-31): v3 does not run on MySQL (maintainer confirmation in issue #3859), ghcr.io/umami-software/umami:3.4.0 with postgres:15.19-alpine, POSTGRES_PASSWORD set-once rule and the 28P01 failure mode, APP_SECRET and TWO_FACTOR_ENCRYPTION_KEY environment variables, 127.0.0.1:3000 binding with Caddy in front, password change via Settings → Profile, ?sslmode=require for hosted databases.
• qde.com — "How to Self-Host Umami: Privacy-Friendly Web Analytics With Docker" (121 days before 2026-10-31): Add Website name/domain semantics, tracking snippet shape and <head> placement, devtools verification of the script and collect requests, ad-blocker blocking even self-hosted scripts, Docker + Nginx + Certbot deployment with backups and updates as the two maintenance jobs.
• vpntierlists.com — "Self-Host Google Analytics Alternative Umami in One Command" (200 days before 2026-10-31): TRACKER_SCRIPT_NAME rename as the ad-blocker defence, one-command installer arc with Caddy.
• selfhosting.sh — "Privacy-Friendly Analytics Setup" (238 days before 2026-10-31): TRACKER_SCRIPT_NAME and COLLECT_API_ENDPOINT renames, admin / umami defaults.
• HackerNoon — "Your Complete Guide to Self-Hosting Umami Analytics with Vercel and Supabase": Umami Cloud as the paid alternative with a free tier, self-host option with Supabase Postgres.

Frequently asked questions about using Umami

Is Umami free to self-host?

Yes. Umami is MIT-licensed open source, and the self-hosted version costs you only the server, the domain, and your maintenance time — there is no license fee and no per-event pricing. The paid alternative is Umami Cloud, which the company offers with a free tier for people who would rather not run infrastructure.

Can Umami run on MySQL?

No — not on v3. The maintainer confirmed in issue #3859 that v3 requires PostgreSQL, and a MySQL database will not work. Older v1/v2-era guides describing MySQL support are stale; if you are installing fresh, use the PostgreSQL compose setup from Step 2.

Does Umami use cookies?

No. Umami collects no personal data by default and uses no cookies, which is why it is commonly described as GDPR-friendly. That said, self-hosting does not exempt you from the law: you still need a privacy policy, and you should understand the consent rules that apply to your own site.

Why is Umami not tracking my visits?

Work through the short checklist: is the snippet in <head> on the page you visited, is data-website-id copied exactly from the website's edit screen, and is your test browser running an ad blocker? Blockers can stop even self-hosted trackers — test in a clean browser profile first, then apply the Step 7 rename. The developer tools' network tab should show the tracker script loading and the collect requests going out.

How do I update Umami in Docker?

Run docker compose pull and then docker compose up -d. Because you pinned the image tag, you control when updates land: check the release notes first, bump the tag deliberately, and let the build run the database migrations. Keep a tested Postgres backup from the backup step before any major-version jump.