umami README

The project's README from github.com/umami-software/umami. As one markdown file: README.md.

Umami Logo

Umami

Umami is a privacy-first analytics platform. Traffic, campaigns, behavior, conversions, and revenue in one place — no cookies, no surveillance, self-hosted or in the cloud.

GitHub Release MIT License Build Status Umami Demo

🚀 Getting Started

A detailed getting started guide can be found at umami.is/docs.

🛠 Installing from Source

Requirements

Get the source code and install packages

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

Configure Umami

Create an .env file with the following:

DATABASE_URL=connection-url

Optional: set API_URL to change the base URL used by internal UI API calls. Relative paths are served under BASE_PATH; absolute URLs are proxied through the local /api route. For example, API_URL=/internal-api or API_URL=https://api.example.com/api.

Optional: set TWO_FACTOR_ENCRYPTION_KEY to a 64-character hex string to enable two-factor authentication. Generate one with openssl rand -hex 32. Two-factor authentication is unavailable and cannot be required until this key is set.

The connection URL format:

postgresql://username:mypassword@localhost:5432/mydb

Build the Application

pnpm run build

The 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.

Start the Application

pnpm run start

By 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.

🐳 Installing with Docker

Umami provides Docker images as well as a Docker compose file for easy deployment.

Docker image:

docker pull docker.umami.is/umami-software/umami:latest

Docker compose (Runs Umami with a PostgreSQL database):

docker compose up -d

🔄 Getting Updates

To get the latest features, simply do a pull, install any new dependencies, and rebuild:

git pull
pnpm install
pnpm build

To update the Docker image, simply pull the new images and rebuild:

docker compose pull
docker compose up --force-recreate -d

🛟 Support

GitHub Twitter LinkedIn Discord

umami (umami-software/umami)

Searching Database…

39.4K ·GitHub
Umami
What is this?Umami is a privacy-first web analytics platform that tracks traffic, campaigns, behavior, conversions, and revenue without cookies or surveillance, as either a self-hosted app or a cloud service.
Is this a hosted service or something I run myself?Both: you can self-host it with Node.js/PostgreSQL or Docker, or use Umami's managed cloud version.
How do I get it running?Clone the source, create an .env file with your database URL, run the build step (which creates the database tables and a default admin user), then start the app; alternatively use the provided Docker image or docker-compose file.
What do I need before installing it myself?A server running Node.js 18.18+ and a PostgreSQL database version v12.14 or newer.
Is two-factor login ready out of the box?No, two-factor authentication stays disabled until you manually generate and set a 64-character TWOFACTORENCRYPTIONKEY in your .env file.
Does it track visitors with cookies like Google Analytics?No, it's built as a cookie-free, non-surveillance alternative to tools like Google Analytics.
Does the default admin login need to be changed?Yes, the build creates a default admin/umami login which you should change immediately after first setup for security.
Can I update it without losing data?Yes, pulling the latest code (or Docker image), reinstalling dependencies, and rebuilding updates the app while keeping your existing database.
What kind of analytics data can I see?Umami covers traffic, campaigns, user behavior, audience segmentation, cohort analysis, conversions, and revenue, similar in scope to Google Analytics but privacy-focused.
What are similar projects?analytics, rybbit, matomo, openanalytics, canonry, posthog, goaccess, redash
Which topics is it in?google-analytics, web-analytics, self-hosted-ai, statistics, charts, privacy-first, analytics, postgresql, docker-compose, dashboard, cloud, web-app
Creator
umami-software
Size
29.3 MB
Stars
39.4K
Updated
CommitSep 17Releasev3.4.0Sep 17
Age
6y
Commits · 90 Days