README

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.



  
  
  
  


---

 🚀 Getting Started

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

---

 🛠 Installing from Source

 Requirements

- A server with Node.js version 18.18+.
- A PostgreSQL database version v12.14+.

 Get the source code and install packages

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


 Configure Umami

Create an .env file with the following:

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

MCP is disabled by default. Set MCP_ENABLED=1 to enable the /mcp endpoint, then
authenticate with an API key generated under Settings → API keys.

The connection URL format:

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


 Build the Application

bash
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

bash
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:

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


Docker compose (Runs Umami with a PostgreSQL database):

bash
docker compose up -d


---

 🔄 Getting Updates

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

bash
git pull
pnpm install
pnpm build


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

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


---

 🛟 Support


  
  
  
  


[release-shield]: https://img.shields.io/github/release/umami-software/umami.svg
[releases-url]: https://github.com/umami-software/umami/releases
[license-shield]: https://img.shields.io/github/license/umami-software/umami.svg
[license-url]: https://github.com/umami-software/umami/blob/master/LICENSE
[build-shield]: https://img.shields.io/github/actions/workflow/status/umami-software/umami/ci.yml
[build-url]: https://github.com/umami-software/umami/actions
[github-shield]: https://img.shields.io/badge/GitHub--blue?style=social&logo=github
[github-url]: https://github.com/umami-software/uma

Top issues

Discussions

Latest release

Umami v3.4.1 is mainly a security hotfix. It updates vulnerable dependencies and the Docker base image. All self-hosted users should upgrade.

 Security

- Upgraded Next.js to 16.4.2 (from 16.3.4 in v3.4.0). This fixes a critical RCE in next/og, SSRF in image optimization, cache poisoning, and an information disclosure issue. 4645
- Upgraded React and React DOM to 19.3.1.
- Pinned the Docker base image to Node 22.23.4-alpine, which includes the October 2026 Node.js security fixes. Rebuild or re-pull your images to pick this up. 4657
- Upgraded @modelcontextprotocol/server to 2.3.1 and @modelco