How to Install Umami Analytics: Complete Step-by-Step Guide for 2025

Comprehensive Umami Installation Methods: From Source Code to Docker Deployment

Are you looking for a privacy-focused, open-source alternative to Google Analytics? Umami offers a lightweight, cookie-free web analytics solution that's easy to set up and completely under your control. This guide covers every installation method to get your Umami analytics dashboard up and running quickly.

Table of Contents

• What is Umami?
• Installation Methods Overview
• Method 1: Installing Umami from Source
• Method 2: Using Docker Compose
• Method 3: Using Pre-built Docker Images
• Running Umami in Production
• Troubleshooting Tips
• FAQ

What is Umami?

Umami is a simple, fast, privacy-focused alternative to Google Analytics. With a clean, user-friendly interface, Umami provides all the essential website statistics without tracking or storing personal visitor data. It's the perfect solution for businesses and developers who prioritize user privacy while still needing accurate website analytics.

Installation Methods Overview

Umami offers three primary installation methods:

1. From Source: Download the code directly from GitHub and build the application yourself - perfect for developers who want full control over the installation process.
2. Docker Compose: Build your own Docker container using docker compose - ideal for developers familiar with containerization.
3. Pre-built Docker Images: Download ready-to-use Docker images - the quickest way to get Umami running with minimal configuration.

Let's dive into each installation method in detail.

Method 1: Installing Umami from Source

Prerequisites

• A server running Node.js v18.18 or newer
• A database system: MySQL (v8.0+) or PostgreSQL (v12.14+)
• Basic command line knowledge

Step 1: Install Yarn Package Manager

npm install -g yarn

Step 2: Clone the Repository and Install Dependencies

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

Step 3: Configure Your Database Connection

Create an .env file in the root directory with your database connection details:

DATABASE_URL={connection url}

Use one of these formats depending on your database:

• PostgreSQL: DATABASE_URL=postgresql://username:mypassword@localhost:5432/mydb
• MySQL: DATABASE_URL=mysql://username:mypassword@localhost:3306/mydb

Step 4: Build the Application

yarn build

During the first build, Umami will:

• Create all required database tables
• Generate a default admin account with:
  • Username: admin
  • Password: umami

Important: Remember to change these default credentials after logging in for the first time!

Step 5: Start the Application

yarn start

Umami will now be running at http://localhost:3000.

Method 2: Using Docker Compose

Docker Compose offers a streamlined way to deploy Umami with PostgreSQL in a containerized environment.

Prerequisites

• Docker and Docker Compose installed on your server
• Basic Docker knowledge

Installation Steps

1. Clone the repository:

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

1. Launch the containers:

docker-compose up -d

This command builds and starts both the Umami application and a PostgreSQL database container in detached mode.

Method 3: Using Pre-built Docker Images

For the quickest setup, Umami provides ready-to-use Docker images with both PostgreSQL and MySQL support.

With PostgreSQL Support

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

With MySQL Support

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

After pulling the image, you can run it with your database configuration as environment variables.

Running Umami in Production

For production environments, it's highly recommended to use a process manager like PM2, which handles automatic restarts and ensures your analytics service stays online.

Setting Up PM2 for Umami

yarn global add pm2
cd umami
pm2 start yarn --name umami -- start
pm2 startup
pm2 save

These commands:

1. Install PM2 globally
2. Start Umami as a managed process
3. Configure PM2 to start on system boot
4. Save the current process list

Troubleshooting Tips

• Database Connection Issues: Double-check your connection string format and credentials
• Port Conflicts: If port 3000 is already in use, modify the port in your environment settings
• Build Errors: Ensure you're using the required Node.js version (18.18+)
• Access Issues: Configure your firewall to allow traffic on Umami's port

FAQ

Q: Is Umami free to use?
A: Yes, Umami is open-source and free to self-host on your own servers.

Q: How does Umami compare to Google Analytics?
A: Umami provides essential website statistics without tracking personal data, making it more privacy-friendly while still delivering key insights.

Q: Can I update Umami without losing data?
A: Yes, your analytics data is stored in your database and persists through application updates.

Q: Is Umami GDPR compliant?
A: Umami is designed with privacy in mind and doesn't use cookies or collect personal information, making it compatible with GDPR requirements.

---

Now that you've successfully installed Umami, you can start tracking website analytics while respecting visitor privacy. Remember to secure your installation by changing the default admin credentials and properly configuring your server's security settings.