Umami is a simple, fast, privacy-focused alternative to Google Analytics.
This is a fork of umami-software/umami with the following additions:
Allows each tracked website to use a custom subdomain (e.g. t.yourdomain.com) for tracking scripts and link URLs, so analytics requests appear first-party and are less likely to be blocked by ad blockers.
- Add and remove custom domains per website under Website Settings → Custom Domains
- One-click DNS verification (checks that your subdomain CNAMEs to the Umami host)
- Verified domains appear as selectable options in the tracking code snippet, link creation form, and pixel creation form
- Feature is opt-in via environment variable:
ENABLE_CUSTOM_DOMAINS=true
CUSTOM_DOMAIN_CNAME_TARGET=your-umami-hostname.com # defaults to APP_URL hostnameYour reverse proxy (Caddy, Nginx, Cloudflare, etc.) must be configured to accept requests on the custom hostnames. SSL termination is handled at the infrastructure level, not by Umami. See docs/custom-domains.md for infrastructure setup examples.
When creating or editing a tracked link, you can now type a custom slug instead of always getting an auto-generated one. The slug field is editable inline with the base URL shown as a prefix. The refresh button still generates a random slug if you prefer. Slugs must contain only letters, numbers, hyphens, and underscores.
Tracked links now resolve at /:slug (e.g. go.yourdomain.com/my-campaign) instead of /:slug previously at /q/:slug. Any existing /q/:slug URLs redirect permanently (301) to the new path.
Import multiple tracked links at once from a CSV file via Links → Import Links.
Supported CSV columns (header names are case-insensitive, parenthetical notes like "(optional)" are ignored):
| Column | Required | Description |
|---|---|---|
Name |
Yes | Display name for the link |
Destination URL |
Yes | The URL to redirect to |
Tracking Domain |
No | A verified custom domain to use for this link |
Link Slug |
No | Custom slug; auto-generated if omitted |
The import dialog shows a preview table before submitting. Rows with validation errors are flagged and skipped; valid rows are imported immediately.
A detailed getting started guide can be found at umami.is/docs.
- A server with Node.js version 18.18+.
- A PostgreSQL database version v12.14+.
git clone https://github.com/umami-software/umami.git
cd umami
pnpm installCreate an .env file with the following:
DATABASE_URL=connection-urlThe connection URL format:
postgresql://username:mypassword@localhost:5432/mydbpnpm run buildThe build step will create tables in your database if you are installing for the first time. It will also create a login user with username admin and password umami.
pnpm run startBy default, this will launch the application on http://localhost:3000. You will need to either proxy requests from your web server or change the port to serve the application directly.
Umami provides Docker images as well as a Docker compose file for easy deployment.
Docker image:
docker pull docker.umami.is/umami-software/umami:latestDocker compose (Runs Umami with a PostgreSQL database):
docker compose up -dTo get the latest features, simply do a pull, install any new dependencies, and rebuild:
git pull
pnpm install
pnpm buildTo update the Docker image, simply pull the new images and rebuild:
docker compose pull
docker compose up --force-recreate -d