Installing from Source

Installing Umami from source gives you complete control over the build process and allows you to customize the application. This method is recommended for developers or advanced users.

Prerequisites

Node.js

Version 18.18 or higher required

PostgreSQL

Version 12.14 or higher required

pnpm

Package manager (installed via npm)

Git

For cloning the repository

Umami uses pnpm as its package manager. Make sure you have it installed before proceeding.

Installation Steps

Install Node.js

Ensure you have Node.js 18.18 or higher:

node --version

If you need to install or update Node.js, visit nodejs.org or use a version manager like nvm:

# Using nvm
nvm install 18
nvm use 18

Install pnpm

Install pnpm globally:

npm install -g pnpm

Verify installation:

pnpm --version

Set Up PostgreSQL Database

You need a running PostgreSQL database. Install PostgreSQL if you haven’t already:

Ubuntu/Debian
macOS
Windows

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Using Homebrew
brew install postgresql@15
brew services start postgresql@15

Create a database for Umami:

# Switch to postgres user (Linux)
sudo -u postgres psql

# Or connect directly (macOS/Windows)
psql postgres

In the PostgreSQL shell:

CREATE DATABASE umami;
CREATE USER umami WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE umami TO umami;
\q

Clone the Repository

Get the Umami source code:

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

Optionally, checkout a specific version:

# List available versions
git tag

# Checkout a specific version
git checkout v3.0.3

Install Dependencies

Install all required packages using pnpm:

pnpm install

This will install all dependencies listed in package.json, including:

Next.js 15.5.9
React 19.2.3
Prisma 6.18.0
And all other required packages

Configure Environment Variables

Create a .env file in the root directory:

touch .env

Add the following configuration:

.env

DATABASE_URL=postgresql://umami:your-secure-password@localhost:5432/umami
APP_SECRET=replace-with-random-string

Generate a secure random string for APP_SECRET:

openssl rand -base64 32

Connection URL format:

postgresql://username:password@hostname:port/database

Example:

DATABASE_URL=postgresql://umami:mypassword@localhost:5432/umami

Build the Application

Build Umami, which will also set up the database schema:

pnpm run build

This command will:

Check environment variables
Generate the Prisma client
Run database migrations
Build the tracker script
Build the Next.js application
Create default admin user

The build process automatically creates tables and a default admin account:

Username: admin
Password: umami

Start Umami

Start the production server:

pnpm start

Umami will start on http://localhost:3000 by default.

Access the Dashboard

Open your browser and navigate to:

http://localhost:3000

Username: admin
Password: umami

Important: Change the default password immediately after your first login!

Development Mode

For development with hot reloading:

pnpm dev

Development mode runs on port 3001 by default (not 3000) and includes:

Hot module replacement
Detailed error messages
Turbopack for faster builds

Build Scripts Explained

Umami’s build process includes several important steps:

pnpm run build

Complete production build:

pnpm run build

This runs:

check-env - Validates required environment variables
build-db - Generates Prisma client
check-db - Verifies database connection
build-tracker - Builds the tracking script (script.js)
build-geo - Downloads GeoIP data
build-app - Builds Next.js application

pnpm run update-db

Run database migrations:

pnpm run update-db

Use this when updating to a new version to migrate the database schema.

pnpm run build-tracker

Rebuild just the tracking script:

pnpm run build-tracker

Useful if you’ve modified the tracker source code.

Configuration Options

Change Port

To run on a different port:

# Production
PORT=8080 pnpm start

# Development (uses -p flag)
pnpm dev -- -p 8080

Use Custom Base Path

If serving Umami from a subdirectory:

.env

BASE_PATH=/analytics

Then rebuild:

pnpm run build

Access at: http://localhost:3000/analytics

Updating Umami

To update to the latest version:

Pull Latest Changes

git pull

Install New Dependencies

pnpm install

Rebuild Application

pnpm build

This will automatically run database migrations.

Restart Server

Stop the current process (Ctrl+C) and start again:

pnpm start

Running as a Service

Using PM2

PM2 is a process manager that keeps Umami running:

Install PM2

npm install -g pm2

Start Umami with PM2

pm2 start pnpm --name umami -- start

Configure Auto-start

pm2 startup
pm2 save

Manage Process

# View status
pm2 status

# View logs
pm2 logs umami

# Restart
pm2 restart umami

# Stop
pm2 stop umami

Using systemd (Linux)

Create a systemd service file:

sudo nano /etc/systemd/system/umami.service

Add the following:

/etc/systemd/system/umami.service

[Unit]
Description=Umami Analytics
After=network.target postgresql.service

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/umami
Environment="NODE_ENV=production"
ExecStart=/usr/bin/pnpm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable umami
sudo systemctl start umami
sudo systemctl status umami

Troubleshooting

Build fails with DATABASE_URL error

Make sure your .env file exists and contains a valid DATABASE_URL:

cat .env

Test database connection:

psql $DATABASE_URL -c "SELECT version();"

Port already in use

Change the port:

PORT=8080 pnpm start

Or find what’s using port 3000:

lsof -i :3000
kill -9 <PID>

Prisma client generation fails

Manually generate the Prisma client:

pnpm run build-db-client

If issues persist, delete generated files:

rm -rf src/generated
pnpm run build-db

Database migration errors

Reset the database (WARNING: deletes all data):

# In PostgreSQL
DROP DATABASE umami;
CREATE DATABASE umami;

Then rebuild:

pnpm run build

Missing dependencies error

Clear pnpm cache and reinstall:

rm -rf node_modules
pnpm store prune
pnpm install

Production Deployment

For production deployments:

Use a strong APP_SECRET
Use secure database credentials
Set up a reverse proxy (nginx, Apache)
Enable HTTPS with SSL certificates
Configure firewall rules
Set up automated backups
Use a process manager (PM2, systemd)
Change default admin password

See Running in Production for detailed production deployment instructions.

Next Steps

Environment Variables

Configure advanced features

Database Setup

Optimize database configuration

Add Website

Start tracking analytics

Production Guide

Deploy to production

Overview

Installation

Configuration

Install from Source

Installing from Source

Prerequisites

Node.js

PostgreSQL

pnpm

Git

Installation Steps

Development Mode

Build Scripts Explained

Configuration Options

Change Port

Use Custom Base Path

Updating Umami

Running as a Service

Using PM2

Using systemd (Linux)

Troubleshooting

Production Deployment

Next Steps

Environment Variables

Database Setup

Add Website

Production Guide

Build docs developers (and LLMs) love

Overview

Installation

Configuration

​Installing from Source

​Prerequisites

Node.js

PostgreSQL

pnpm

Git

​Installation Steps

​Development Mode

​Build Scripts Explained

​Configuration Options

​Change Port

​Use Custom Base Path

​Updating Umami

​Running as a Service

​Using PM2

​Using systemd (Linux)

​Troubleshooting

​Production Deployment

​Next Steps

Environment Variables

Database Setup

Add Website

Production Guide

Build docs developers (and LLMs) love

Installing from Source

Prerequisites

Installation Steps

Development Mode

Build Scripts Explained

Configuration Options

Change Port

Use Custom Base Path

Updating Umami

Running as a Service

Using PM2

Using systemd (Linux)

Troubleshooting

Production Deployment

Next Steps