Skip to main content

​
Quickstart Guide

This guide will help you get Umami running quickly using Docker Compose. You’ll have a working analytics dashboard in just a few minutes.

​
Prerequisites

Before you begin, make sure you have:
  • Docker and Docker Compose installed on your system
  • Basic command line knowledge
  • A domain or server to host Umami (optional for local testing)

​
Installation with Docker Compose

1

Clone the Repository

First, get the Umami source code:
git clone https://github.com/umami-software/umami.git
cd umami
2

Start Umami with Docker Compose

The repository includes a docker-compose.yml file that sets up both Umami and PostgreSQL:
docker compose up -d
This command will:
  • Pull the latest Umami image from ghcr.io/umami-software/umami:latest
  • Set up a PostgreSQL 15 database
  • Create persistent storage for your data
  • Start Umami on port 3000
The -d flag runs the containers in detached mode (in the background).
3

Verify Installation

Wait a few seconds for the services to start, then check they’re running:
docker compose ps
You should see both umami and db containers running and healthy.
4

Access the Dashboard

Open your browser and navigate to:
http://localhost:3000
You’ll see the Umami login page.

​
Initial Login

Default Credentials: The initial installation creates a default admin account with:
  • Username: admin
  • Password: umami
You MUST change this password immediately after logging in.
1

Log In

Use the default credentials to log in:
  • Username: admin
  • Password: umami
2

Change Your Password

After logging in:
  1. Click on the Settings icon in the navigation
  2. Go to Profile or Password settings
  3. Enter a strong new password
  4. Save your changes

​
Add Your First Website

Now let’s add a website to track:
1

Navigate to Websites

Click on the Websites tab in the main navigation.
2

Add Website

Click the Add Website button and fill in the details:
  • Name: A friendly name for your website (e.g., “My Blog”)
  • Domain: Your website domain (e.g., “myblog.com”)
  • Share URL: Optional - enable public stats sharing
Click Save to create the website.
3

Get Your Tracking Code

After creating the website, click on it to view the tracking code:
  1. Click the Edit or Tracking Code button
  2. Copy the provided JavaScript snippet
It will look like this:
<script async src="http://localhost:3000/script.js" 
        data-website-id="your-website-id"></script>

​
Install Tracking Script

Add the tracking script to your website:
Add the script tag to the <head> section of your HTML:
<!DOCTYPE html>
<html>
  <head>
    <title>My Website</title>
    <script async src="http://localhost:3000/script.js" 
            data-website-id="your-website-id"></script>
  </head>
  <body>
    <!-- Your content -->
  </body>
</html>
The tracking script is lightweight (< 2KB) and loads asynchronously, so it won’t impact your page load times.

​
View Your First Pageview

Let’s verify everything is working:
1

Visit Your Website

Open your website in a browser (the one where you added the tracking script).
2

Check the Dashboard

Go back to your Umami dashboard and click on your website. You should see:
  • Your first pageview appearing in real-time
  • The page URL in the “Pages” section
  • Browser and device information
  • Geographic location (if GeoIP is configured)
3

Explore the Dashboard

The dashboard shows:
  • Real-time visitors: Current active users
  • Views: Total pageviews
  • Unique visitors: Distinct visitor count
  • Bounce rate: Single-page visits
  • Visit duration: Average time on site
  • Top pages: Most visited pages
  • Referrers: Traffic sources
  • Browsers, OS, Devices: Technology breakdown
  • Countries: Geographic distribution

​
Next Steps

Track Custom Events

Learn how to track button clicks, form submissions, and custom interactions.

Configure Environment Variables

Customize Umami with environment variables for advanced features.

Set Up a Custom Domain

Configure a reverse proxy with nginx or use a platform’s domain features.

Explore the API

Use the Umami API to integrate analytics into your applications.

​
Troubleshooting

  • Check that Umami is running: docker compose ps
  • Verify the script URL is correct and accessible
  • Check browser console for errors
  • Ensure your website-id is correct
  • Verify the tracking script is in the <head> section
  • Check that the script has loaded in browser DevTools > Network tab
  • Wait a few seconds - data updates in near real-time
  • Check browser console for CORS errors
  • Ensure Docker containers are running: docker compose ps
  • Check port 3000 isn’t already in use
  • View logs: docker compose logs umami
  • Try restarting: docker compose restart
  • Check both containers are healthy: docker compose ps
  • View database logs: docker compose logs db
  • Ensure the DATABASE_URL is correct in docker-compose.yml
  • Try recreating containers: docker compose down && docker compose up -d
For production deployments, check out the detailed Installation Guides for Docker, Railway, Vercel, and source installations.

Build docs developers (and LLMs) love

Get started for freeTalk to us