Welcome to Umami

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• app.json
• package.json
• src/tracker/index.js
• src/lib/constants.ts
• scripts/seed-data.ts
• src/app/(main)/console/[websiteId]/TestConsolePage.tsx
• podman/README.md

Umami is a simple, fast, and privacy-focused web analytics alternative to Google Analytics. It is designed to provide you with powerful web traffic insights without compromising user privacy. The system is self-hostable, allowing you to maintain full control over your data.

This document provides a high-level overview of the Umami system, its architecture, installation procedures, and core components, based on the project's source code. The primary components are a Next.js application for the dashboard, a PostgreSQL database for data storage, and a lightweight JavaScript tracker for data collection.

Architecture Overview

Umami's architecture consists of three main parts: the core application (a Next.js server), a database (PostgreSQL), and a client-side JavaScript tracker. The tracker is embedded in a target website, collects event data, and sends it to the Umami server, which then processes and stores the data in the database for analysis in the Umami dashboard.

This diagram illustrates the high-level data flow of the Umami system.

Installation

Umami can be installed from the source code or by using Docker.

From Source

Installing from source requires Node.js (v18.18+) and a PostgreSQL database (v12.14+).

This flowchart shows the installation steps from the source code.

1. Get the source code and install packages:

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

2. Configure Umami: Create a .env file with the DATABASE_URL.

   # .env
   DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb
   

3. Build the Application: This step also creates the necessary database tables and a default user (admin/umami).

   pnpm run build
   

4. Start the Application:

   pnpm run start
   

By default, the application runs on http://localhost:3000.

Sources: README.md:16-43

With Docker

Umami provides Docker images for easier deployment. A docker-compose.yml file is available to run Umami with a PostgreSQL database.

# Pull the latest image
docker pull docker.umami.is/umami-software/umami:latest

# Run with Docker Compose
docker compose up -d

A Podman deployment is also supported, with similar steps using podman-compose.

*Sources: README.md:47-57, podman/README.md *

Tracking Script

The core of Umami's data collection is a JavaScript file, typically named script.js, which is generated during the build process. This script is embedded into the website you want to track.

Sources: src/tracker/index.js, src/app/(main)/console/[websiteId]/TestConsolePage.tsx:101-105

Integration

To integrate Umami, you add a <script> tag to the <head> section of your website's HTML. The script requires a data-website-id attribute to associate the collected data with the correct site in your Umami instance.

<script async data-website-id="your-website-id" src="http://your-umami-instance/script.js"></script>

Sources: src/app/(main)/console/[websiteId]/TestConsolePage.tsx:101-105, src/components/messages.ts:241-244

Configuration Attributes

The tracker's behavior can be customized using data-* attributes on the script tag.

Attribute	Description	Default
data-website-id	Required. The unique ID for the website to track.	null
data-host-url	The URL of your Umami instance.	Inferred from script src
data-auto-track	Enables or disables automatic tracking of page views.	true
data-do-not-track	Enables respecting the browser's "Do Not Track" setting.	false
data-domains	A comma-separated list of domains to track.	"" (all domains)
data-cache	Enables a cache to be sent with the request to the server.	false
data-tag	A tag to be associated with all events from this tracker instance.	undefined

Sources: src/tracker/index.js:20-32

Data Collection Flow

The tracker automatically captures page views and can be configured to track custom events. It sends this data as a JSON payload to the Umami server's collection endpoint.

This sequence diagram shows how a tracking event is captured and sent to the server.

Global umami Object

The tracker exposes a global umami object on the window for manual tracking.

• umami.track(name, data): Tracks a custom event. The name can be a string for an event name or a function to modify the payload. The data object contains custom event data.
• umami.identify(id, data): Associates a user with a specific ID and custom data. This clears the session cache.

Example usage from the test console:

// Track a simple page view
window.umami.track(props => ({
  ...props,
  url: '/page-view',
  referrer: 'https://www.google.com',
}));

// Track a custom event with data
window.umami.track('track-event-with-data', {
  test: 'test-data',
  number: 1,
});

// Identify a user
window.umami.identify({
  userId: 123,
  name: 'brian',
});

Sources: src/tracker/index.js:172-206, src/app/(main)/console/[websiteId]/TestConsolePage.tsx:16-98

System Constants & Data Model

The application relies on a set of predefined constants for its core logic, including data types, event types, roles, and permissions.

Event and Data Types

Umami categorizes collected data and events into specific types.

Constant	Value	Description
EVENT_TYPE.pageView	1	A user viewing a page.
EVENT_TYPE.customEvent	2	A custom event triggered via umami.track().
DATA_TYPE.string	1	A string data type.
DATA_TYPE.number	2	A number data type.
DATA_TYPE.boolean	3	A boolean data type.
DATA_TYPE.date	4	A date data type.
DATA_TYPE.array	5	An array data type.
Sources: src/lib/constants.ts:74-94

User Roles and Permissions

Umami has a role-based access control (RBAC) system to manage user permissions.

Role	Description
admin	Has all permissions.
user	Can create and manage their own websites and teams.
viewOnly	Has no permissions; a read-only role.
teamOwner	Full control over a team and its websites.
teamManager	Can manage team websites and members.
teamMember	Can manage websites within a team.
teamViewOnly	Read-only access to a team's websites.
Sources: src/lib/constants.ts:114-124, src/lib/constants.ts:134-162

Development and Testing

The repository includes scripts and tools to aid in development and testing.

Seeding Sample Data

The seed-data.ts script is used to generate realistic sample analytics data for local development. It can create data for a specified number of days and can clear existing demo data. This is useful for testing the UI and analytics queries without needing live traffic.

Usage:

# Generate 30 days of data
npm run seed-data

# Generate 90 days of data and clear previous data
npm run seed-data -- --days 90 --clear

The script is blocked from running in production environments.

*Sources: scripts/seed-data.ts *

Test Console

The application includes a "Test Console" page for each website. This page provides an interactive environment to test tracking functionality, including:

• Page link navigation.
• Click events via data-umami-event attributes.
• Manual JavaScript events using umami.track() and umami.identify().
• Revenue and event data generation.

This console is a valuable tool for developers to verify that their tracking implementation is working as expected.

*Sources: src/app/(main)/console/[websiteId]/TestConsolePage.tsx *