Installation Guide

Relevant source files

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

• README.md
• package.json
• scripts/check-db.js
• app.json
• scripts/build-geo.js
• scripts/seed-data.ts
• next.config.ts

Umami is a simple, fast, privacy-focused alternative to Google Analytics. This guide provides comprehensive instructions for installing the Umami application from the source code, as well as using Docker for deployment. It covers prerequisites, configuration, building, and running the application.

Sources: README.md:9-11, app.json:2-3

Prerequisites

Before installing from source, ensure your environment meets the following requirements:

• Node.js: version 18.18 or higher.
• PostgreSQL: version 12.14 or higher. The database check script specifically verifies against a minimum version of 9.4.0.

Sources: README.md:20-22, scripts/check-db.js:12

Installation from Source

This method involves cloning the repository and building the application manually.

1. Get Source Code and Install Dependencies

First, clone the git repository and navigate into the project directory. Then, use pnpm to install the required packages.

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

The pnpm install command will install all dependencies listed in package.json.

Sources: README.md:24-27, package.json

2. Configure Environment

Create a .env file in the root of the project. This file will hold your environment-specific configurations. The most critical variable is the database connection URL.

Environment Variables

Variable	Description	Required	Example
DATABASE_URL	The connection URL for your PostgreSQL database.	Yes	postgresql://username:password@localhost:5432/mydb
APP_SECRET	A secret key used to generate unique values for the installation. Required for platforms like Heroku.	For some deployments	a-very-long-and-random-string

Example .env file:

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

Sources: README.md:29-35, app.json:8-14

3. Build the Application

The build process is orchestrated by a single pnpm script which executes several sub-tasks in sequence.

pnpm run build

This command will:

1. Check for the presence of required environment variables.
2. Set up the database, including generating the Prisma client.
3. Verify the database connection and version.
4. Apply any pending database migrations.
5. Build the tracker script (script.js).
6. Download the geolocation database.
7. Build the Next.js application.

The build step also creates the initial database tables and a default user with username admin and password umami.

Sources: README.md:37-42, package.json:13

Build Process Flow

The build script in package.json runs a series of other scripts. The following diagram illustrates this workflow.

• build-db: This script generates the Prisma client needed to interact with the database.
• check-db: A crucial script that verifies the database setup. See the Database Checks section for details.
• build-geo: This script downloads a GeoLite2 City database for geolocation features. It can pull from MaxMind directly if a MAXMIND_LICENSE_KEY is provided, or a redistributed version from GitHub.
• build-app: This runs next build to compile the Next.js frontend.

Sources: package.json:13-28, scripts/build-geo.js:15-22

4. Start the Application

Once the build is complete, start the application server.

pnpm run start

By default, the application will be available at http://localhost:3000. For production use, you may need to proxy requests from a web server like Nginx or change the default port.

Sources: README.md:44-48

Docker Installation

For a more streamlined setup, Umami can be run using Docker.

• Pull the image:

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

• Run with Docker Compose:
  This method starts both the Umami application and a PostgreSQL database.

  docker compose up -d
  

The start-docker script defined in package.json handles the sequence of checking the database, updating the tracker, and starting the server within the Docker environment.

Sources: README.md:50-59, package.json:16

Core Installation Scripts

The installation and build process relies on several key scripts defined in package.json.

Script	Description
build	The main build script that runs all necessary sub-tasks for a production build from source.
start	Starts the Next.js production server.
check-db	Executes scripts/check-db.js to validate the database connection, version, and apply migrations.
build-db	Generates the Prisma client based on the database schema.
build-geo	Executes scripts/build-geo.js to download the GeoIP database.
seed-data	Populates the database with sample data for testing.

Sources: package.json:13-39

Database Checks

The check-db.js script is vital for ensuring the database is correctly configured and up-to-date. It performs the following steps:

1. Environment Check: Verifies that DATABASE_URL is set.
2. Connection Check: Attempts to connect to the database using the provided URL.
3. Version Check: Queries the database version and ensures it is at least 9.4.0.
4. Migration: Runs prisma migrate deploy to apply any outstanding database schema migrations, unless SKIP_DB_MIGRATION is set.

The following diagram shows the flow of the check-db script.

Optional: Seed Sample Data

After a successful installation, you can generate sample analytics data for development and testing purposes. The seed-data script creates two demo websites with realistic traffic patterns.

pnpm run seed-data

You can customize the data generation with the following options:

• --days <number>: Number of days of data to generate (default: 30).
• --clear: Clear existing demo data before generating new data.
• --verbose: Show detailed progress.

Example: Generate 90 days of data.

pnpm run seed-data -- --days 90

This script is blocked from running in production environments.

Sources: scripts/seed-data.ts:10-16, package.json:38

Getting Updates

To update an existing installation from source, pull the latest changes, install any new dependencies, and rebuild the application.

git pull
pnpm install
pnpm build

For Docker-based installations, pull the latest images and recreate the containers.

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

Sources: README.md:61-70