Umami Analytics

You can deploy Umami using Docker images or Docker Compose.

Using Docker Image

Pull the latest image from the Umami registry:

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

Using Docker Compose

To run Umami along with a managed PostgreSQL database, use the provided compose file:

docker compose up -d

To deploy Umami using Podman, follow these steps:

1. Prepare the environment file: Rename env.sample to .env.
2. Configure credentials: Edit the .env file and ensure you set the required passwords at a minimum.
3. Launch the application: Run podman-compose up -d to start Umami in detached mode.

To stop the application, run: podman-compose down

# Prepare and configure
cp env.sample .env
# (Edit .env with your passwords)

# Start Umami
podman-compose up -d

# Stop Umami
podman-compose down

To update your Umami installation, follow the steps corresponding to your deployment method.

Updating from Source

Pull the latest code, reinstall dependencies, and rebuild:

git pull
pnpm install
pnpm build

Updating Docker Compose

Pull the latest images and recreate the containers:

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

To install Umami from source, ensure your environment meets the requirements, clone the repository, install dependencies, configure the environment, build, and start the application.

Requirements

• Node.js: version 18.18+
• PostgreSQL: version v12.14+

Installation Steps

1. Clone and Install Dependencies:

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

2. Configure Environment: Create an .env file in the root directory and provide the DATABASE_URL.
3. Build the Application:

   pnpm run build

   Note: The build step automatically creates database tables and an initial admin user (username: admin, password: umami) if it is a fresh installation.
4. Start the Application:

   pnpm run start

   The application defaults to http://localhost:3000.

Umami provides two types of user behavior tracking through its recorder script:

1. Session Replay: Uses rrweb to capture DOM mutations and reconstruct the user's session. It buffers events and flushes them to /api/record periodically or when the buffer reaches a size limit (REPLAY_MAX_PAYLOAD_SIZE). If a single event (like a full snapshot) is too large, it is split into fragments of type umami:rrweb-event-fragment.
2. Heatmaps: Captures user interactions like click and scroll. It tracks viewport dimensions, page dimensions, and scroll percentages. Heatmap events are buffered and flushed to /api/record (with type: 'heatmap') either when the buffer reaches HEATMAP_FLUSH_EVENT_COUNT (20) or after a HEATMAP_FLUSH_INTERVAL (5000ms).

Both features are subject to a sampleRate (default 0.15) to reduce overhead and data volume.

The recorder supports different levels of data masking to protect user privacy. This is configured via the maskLevel setting received from the Umami API.

• moderate (default): Masks all input elements (maskAllInputs: true).
• strict: Masks all input elements and all text content using the maskTextSelector: '*' selector.

Masking is applied during the rrweb recording process to ensure sensitive information is not captured in the DOM snapshots.

When sending custom data with events, use the EventData interface. To maintain performance, Umami enforces the following constraints on data:

• Numbers: Maximum precision of 4.
• Strings: Maximum length of 500 characters.
• Arrays: Converted to a string with a maximum length of 500.
• Objects: Maximum of 50 properties (arrays are treated as a single property).

EventDataValue can be a boolean, number, string, null, EventData, or an array of these types.

const myData: EventData = {
  name: 'newsletter',
  id: 123,
  is_active: true
};

umami.track('signup', myData);

Umami uses environment variables for configuration. At a minimum, you must provide a PostgreSQL connection string.

Required Variables

• DATABASE_URL: The connection string for your PostgreSQL database. Format: postgresql://username:mypassword@localhost:5432/mydb

Optional Variables

• API_URL: Sets the base URL used by internal UI API calls.
  • Use a relative path for BASE_PATH (e.g., API_URL=/internal-api).
  • Use an absolute URL to proxy through the local /api route (e.g., API_URL=https://api.example.com/api).

DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb
API_URL=/internal-api

The Umami recorder is initialized via a <script> tag. It automatically reads configuration from data- attributes on the script element itself. To ensure the recorder functions correctly, the following attributes must be present:

• data-website-id: The unique ID of the website being tracked.
• data-host-url: (Optional) The base URL of your Umami instance. If omitted, it defaults to the directory of the current script or __COLLECT_API_HOST__.

When the script loads, it fetches configuration from ${hostBase}/api/websites/${website}/recorder to determine if recording is enabled and to set parameters like sampleRate, maskLevel, and maxDuration.

<!-- Example of how the script should be included in your HTML -->
<script
  src="https://your-umami-instance.com/recorder.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-host-url="https://your-umami-instance.com"
></script>

The db service uses standard PostgreSQL environment variables to initialize the database:

• POSTGRES_DB: The name of the database to create (default: umami).
• POSTGRES_USER: The superuser username (default: umami).
• POSTGRES_PASSWORD: The password for the superuser (default: umami).