Skip to main content

​
Introduction

Umami is a simple, fast, privacy-focused alternative to Google Analytics that you can self-host on your own infrastructure. This guide will help you get started with self-hosting Umami.

​
Why Self-Host Umami?

Privacy-First

Full control over your analytics data with no third-party tracking

Open Source

MIT licensed with complete source code transparency

Lightweight

Minimal resource requirements with efficient data storage

GDPR Compliant

No cookies, no personal data collection by default

​
Requirements

Before you begin, ensure you have:

Node.js

Version 18.18 or higher

Database

PostgreSQL v12.14+ or ClickHouse (optional)

Server

Linux, macOS, or Windows with 1GB+ RAM

Package Manager

pnpm (recommended) or npm
For production deployments, we recommend at least 2GB of RAM and 20GB of disk space.

​
Deployment Options

Umami offers multiple deployment methods to suit your infrastructure:

​
Quick Start with Docker

1

Clone the repository

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

Start with Docker Compose

docker compose up -d
This command will:
  • Pull the latest Umami image
  • Start a PostgreSQL database
  • Initialize the database schema
  • Start Umami on port 3000
3

Access Umami

Open your browser and navigate to http://localhost:3000
Default credentials:
  • Username: admin
  • Password: umami
Change these immediately after first login!

​
Quick Start from Source

1

Clone and install dependencies

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

Configure environment variables

Create a .env file in the root directory:
DATABASE_URL=postgresql://username:password@localhost:5432/umami
Replace with your actual PostgreSQL connection details.
3

Build the application

pnpm build
The build process will automatically create database tables and a default admin user.
4

Start the application

pnpm start
Umami will be available at http://localhost:3000

​
Database Options

Umami supports two database backends:
Recommended for most users
  • Mature, reliable, and well-documented
  • Full SQL support with ACID compliance
  • Minimum version: 12.14
  • Ideal for small to medium-sized deployments
DATABASE_URL=postgresql://user:password@localhost:5432/umami

​
Default Credentials

After installation, Umami creates a default admin account:
  • Username: admin
  • Password: umami
You must change these credentials immediately after your first login for security reasons.

​
Next Steps

Now that you have Umami running, here’s what to do next:

Docker Deployment

Learn advanced Docker configuration options

Environment Variables

Configure Umami with environment variables

PostgreSQL Setup

Optimize your PostgreSQL database

Upgrading

Keep your instance up to date

​
Common Issues

Change the port by setting the PORT environment variable:
PORT=3001 pnpm start
Or modify the docker-compose.yml ports section:
ports:
  - "3001:3000"
Verify your DATABASE_URL is correct:
  1. Check the hostname, port, username, and password
  2. Ensure PostgreSQL is running
  3. Verify the database exists
  4. Check firewall rules allow connections
Test the connection:
psql postgresql://username:password@localhost:5432/umami
Umami requires Node.js 18.18 or higher. Check your version:
node --version
Upgrade Node.js if needed using nvm:
nvm install 18
nvm use 18

​
Support

Need help? Join the Umami community:

Build docs developers (and LLMs) love

Get started for freeTalk to us