Umami

Umami is an open source analytics platform that tracks traffic, campaigns, behavior and conversions without cookies. It is a Next.js application backed by PostgreSQL, built with pnpm and Prisma.

Requirements

Create a PostgreSQL database (version 12.14 or newer) on the app's Databases tab. Hatchbox attaches it as DATABASE_URL, which is the only variable Umami requires.

Building the Next.js app is memory hungry: the build peaks at about 4 GB. Use a server with 4 GB of RAM, or add swap on a 2 GB server.

Repository

Fork the upstream repository and deploy your fork using the master branch, which tracks the latest release (the dev branch is the development branch).

https://github.com/umami-software/umami.git

Make three small changes in your fork:

1. Add a .node-version file containing 22.23.3. Upstream has no Node version file and its Docker image uses Node 22.
2. Add "packageManager": "pnpm@12.3.4" to package.json. Umami pins "engines": { "pnpm": "12.3.4" }, and pnpm refuses to install with a different version. The packageManager field lets Corepack pick the right one.
3. Add the .hatchbox/post-build script below.

Environment Variables

DATABASE_URL=postgresql://...        # set automatically by Hatchbox
DISABLE_TELEMETRY=1                  # optional
TWO_FACTOR_ENCRYPTION_KEY=...        # optional, `openssl rand -hex 32`, enables 2FA

Set TRACKER_SCRIPT_NAME if you want to serve the tracker under a name other than script.js. All other settings are optional and documented at umami.is/docs.

Build Scripts

Hatchbox runs pnpm install automatically, but not the build. Umami's pnpm run build generates the Prisma client, runs prisma migrate deploy, downloads the GeoLite2 database into geo/, builds the tracker script and compiles the Next.js app. Migrations should only run on one server, so the script skips them unless the cron role is present.

.hatchbox/post-build

#!/usr/bin/env bash
set -e

if [ "$CRON" != "true" ]; then
  export SKIP_DB_MIGRATION=1
fi

pnpm run build

Make the file executable before committing it.

Processes

Add one process on the web servers:

• web: pnpm exec next start -p $PORT

First Login

The first database migration creates an admin account with username admin and password umami. Sign in and change the password immediately under Settings.

Notes

Umami keeps all state in PostgreSQL, so nothing needs to persist on disk between deploys. Add a website in Settings, then copy the tracking snippet into your site. To update, merge the upstream master branch into your fork and deploy; the build script applies any new migrations.