Skip to content
Get packs

Guide · Open source

How to use Umami: install, configure and start analytics

Updated · written with AI from the project's own documentation and checked against our catalogue data

Umami is a privacy-first web and product analytics platform. It shows traffic, campaigns, user behavior, conversions and revenue in one place, without cookies or surveillance, and you can run it on your own server or use the hosted cloud version. This guide walks through what you need, how to install Umami from source or with Docker, how to configure it, and how to keep it updated.

Umamiumami-software/umami · ★ 39.9k · MIT

Quick start

  1. 1Check prerequisites. Confirm you have Node.js 18.18+ and PostgreSQL 12.14+, or Docker for the container route.
  2. 2Clone the repository. Run git clone on the umami repository and move into the umami folder.
  3. 3Install packages. Run pnpm install to install the dependencies.
  4. 4Set DATABASE_URL. Create a .env file containing a PostgreSQL connection URL in the DATABASE_URL setting.
  5. 5Build the app. Run pnpm run build, which creates the database tables on a first install.
  6. 6Start Umami. Run pnpm run start and open http://localhost:3000, or use docker compose up -d instead.

What you need before you install Umami

Installing from source requires a server running Node.js 18.18 or newer and a PostgreSQL database version 12.14 or newer. The source install also uses pnpm to install packages and build the app. The Docker route needs Docker instead.

Umami's README only lists PostgreSQL as the supported database, so plan on PostgreSQL if you self-host.

  • Node.js 18.18+ (source install)
  • PostgreSQL 12.14+
  • pnpm (source install)
  • Docker (Docker install)

Install Umami from source

Clone the repository, move into the folder and install the packages with pnpm.

git clone https://github.com/umami-software/umami.git cd umami pnpm install

Configure the database connection

Create a file named .env in the project folder. It must contain DATABASE_URL, set to a PostgreSQL connection URL in the format shown below. Optional settings such as API_URL, TWO_FACTOR_ENCRYPTION_KEY and MCP_ENABLED are also described in the README.

  • API_URL changes the base URL used by internal UI API calls.
  • TWO_FACTOR_ENCRYPTION_KEY enables two-factor authentication when set to a 64-character hex string. The README suggests generating one with openssl rand -hex 32.
  • MCP_ENABLED=1 turns on the /mcp endpoint. It is disabled by default.
DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb

Build and start the application

Build the app first. According to the README, the build step creates the tables in your database on a first install and creates a login user with username admin and password umami. Change that password after your first login.

Then start the app. By default it runs at http://localhost:3000. To serve it on a public address, put a reverse proxy such as nginx in front of it or change the port.

pnpm run build pnpm run start

Install Umami with Docker

Umami provides Docker images and a Docker compose file. The compose file runs Umami together with a PostgreSQL database, which is the simplest route if you do not want to manage Node.js yourself.

To pull the image on its own, use the command below. To start the compose setup, run the second command from the project folder.

docker pull docker.umami.is/umami-software/umami:latest docker compose up -d

Update Umami

For a source install, pull the latest code, install any new dependencies and rebuild. For Docker, pull the new images and recreate the containers.

git pull pnpm install pnpm build

What people use it for

  • Showing page traffic and campaign performance on a website without a cookie banner
  • Keeping visitor data on your own server for compliance or control
  • Tracking conversions and revenue alongside traffic in one dashboard
  • Giving a marketing team campaign reporting without third-party scripts that set cookies

Frequently asked questions

Is Umami free?

Umami is released under the MIT licence, so the source code is open source. The README describes a self-hosted option and a cloud option; it does not list prices, so check umami.is for current cloud pricing.

Does Umami use cookies?

Umami is designed to avoid cookies and tracking that identifies individual visitors. This is the main reason site owners use it for stats without a cookie banner.

What database does Umami need?

The README lists PostgreSQL 12.14 or newer as the database requirement. It does not describe MySQL or other databases, so do not plan on them.

Can I run Umami with Docker?

Yes. Umami provides a Docker image and a Docker compose file that runs Umami with a PostgreSQL database. Start it with docker compose up -d.

What is the default login after installation?

The build step creates a user with username admin and password umami. Change the password as soon as you sign in, because the default is publicly documented.

What are alternatives to Umami?

Comparable projects include Matomo, Plausible, PostHog and Simple Analytics. Umami is a good fit if you want self-hosting with a Node.js and PostgreSQL stack, while other tools may suit different hosting or feature needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Umami suits website owners and developers who want cookieless traffic stats and are comfortable running a Node.js app with PostgreSQL, or using Docker. If you want zero server setup, or need MySQL or a detailed feature list the README does not provide, look at a hosted alternative or another tool such as Plausible or Matomo.

Install options & downloads