# Umami

Umami is a privacy-focused, cookie-free web analytics alternative to Google Analytics

[Umami](https://github.com/umami-software/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.