Docker Installation

Docker is the recommended way to install Umami. This guide covers both Docker Compose (easiest) and standalone Docker installation.

Prerequisites

Make sure you have Docker and Docker Compose installed on your system. Visit docker.com for installation instructions.

Required:

Docker Engine 20.10+
Docker Compose v2.0+ (included with Docker Desktop)
At least 512MB RAM
1GB free disk space

Quick Start with Docker Compose

The fastest way to get Umami running with a PostgreSQL database.

Get the Docker Compose File

Clone the repository or download the docker-compose.yml file:

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

Or create your own docker-compose.yml file:

docker-compose.yml

---
services:
  umami:
    image: ghcr.io/umami-software/umami:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      APP_SECRET: replace-me-with-a-random-string
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: umami
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

Configure Environment Variables

Important: Change the APP_SECRET to a random string before deploying to production!

You can generate a random secret:

openssl rand -base64 32

Or use an online generator. Update your docker-compose.yml:

environment:
  DATABASE_URL: postgresql://umami:umami@db:5432/umami
  APP_SECRET: your-random-secret-string-here

Start the Containers

Launch Umami and PostgreSQL:

docker compose up -d

The -d flag runs containers in detached mode (background).

Verify Installation

Check that both containers are running:

docker compose ps

You should see both umami and db with status “Up” and “healthy”.View logs to confirm successful startup:

docker compose logs umami

Access Umami

Open your browser and navigate to:

http://localhost:3000

Username: admin
Password: umami

Change the default password immediately after logging in!

Using Pre-built Docker Image

You can also run Umami using just Docker (without Docker Compose) if you have an external PostgreSQL database.

Pull the Image

docker pull ghcr.io/umami-software/umami:latest

Alternatively, you can use the Docker Hub image:

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

Run the Container

With External Database
With Docker Network

If you have an existing PostgreSQL database:

docker run -d \
  --name umami \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://username:password@hostname:5432/dbname \
  -e APP_SECRET=your-random-secret \
  --restart always \
  ghcr.io/umami-software/umami:latest

Replace the DATABASE_URL with your actual database connection string.

If your PostgreSQL is in another Docker container:

# Create a network
docker network create umami-network

# Run PostgreSQL
docker run -d \
  --name postgres \
  --network umami-network \
  -e POSTGRES_DB=umami \
  -e POSTGRES_USER=umami \
  -e POSTGRES_PASSWORD=umami \
  -v umami-db-data:/var/lib/postgresql/data \
  postgres:15-alpine

# Run Umami
docker run -d \
  --name umami \
  --network umami-network \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://umami:umami@postgres:5432/umami \
  -e APP_SECRET=your-random-secret \
  --restart always \
  ghcr.io/umami-software/umami:latest

Configuration Options

Environment Variables

DATABASE_URL

Required. PostgreSQL connection string

APP_SECRET

Required. Random string for securing sessions and data

PORT

Optional. Port to run on (default: 3000)

BASE_PATH

Optional. Base path for reverse proxy setups

See the full list in Environment Variables.

Volume Mounts

The Docker Compose setup creates a persistent volume for PostgreSQL data:

volumes:
  - umami-db-data:/var/lib/postgresql/data

This ensures your analytics data persists across container restarts.

Building from Source

To build your own Docker image from source:

Clone Repository

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

Build Image

docker build -t umami:local .

This uses the Dockerfile in the repository.

Run Your Image

docker run -d \
  --name umami \
  -p 3000:3000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e APP_SECRET=your-secret \
  umami:local

Build Arguments

The Dockerfile supports build arguments:

docker build \
  --build-arg NODE_IMAGE_VERSION=22-alpine \
  --build-arg BASE_PATH=/analytics \
  -t umami:custom .

Available arguments:

NODE_IMAGE_VERSION: Node.js base image version (default: 22-alpine)
BASE_PATH: URL base path for serving Umami
PRISMA_VERSION: Prisma version to use (default: 6.19.0)

Management Commands

View Logs

# View all logs
docker compose logs

# Follow logs in real-time
docker compose logs -f umami

# Last 100 lines
docker compose logs --tail=100 umami

Restart Containers

# Restart all services
docker compose restart

# Restart just Umami
docker compose restart umami

Stop and Remove

# Stop containers
docker compose stop

# Stop and remove containers (keeps data)
docker compose down

# Remove everything including volumes
docker compose down -v

Updating Umami

Pull Latest Image

docker compose pull

Recreate Containers

docker compose up -d --force-recreate

Verify Update

Check the version in Umami settings or view logs:

docker compose logs umami | grep version

Database migrations run automatically on startup, so your schema will be updated when you upgrade to a new version.

Troubleshooting

Containers won't start

Check logs for errors:

docker compose logs

Common issues:

Port 3000 already in use (change port mapping)
DATABASE_URL incorrect
Insufficient memory or disk space

Database connection failed

Verify database is healthy:

docker compose ps db

Check DATABASE_URL format:

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

Ensure database is reachable from Umami container.

Can't access localhost:3000

Check container is running: docker compose ps
Verify port mapping in docker-compose.yml
Check firewall settings
Try http://127.0.0.1:3000 instead

Data lost after restart

Ensure volumes are properly configured:

docker volume ls

You should see umami-db-data volume. If not, your data wasn’t persisted.

Production Deployment

For production deployments, you MUST:

Change the APP_SECRET to a strong random value
Use strong database passwords
Set up a reverse proxy (nginx, Traefik, Caddy)
Enable HTTPS/SSL
Configure backups for the PostgreSQL volume
Change the default admin password

See Configuration for production deployment best practices including reverse proxy setup and SSL configuration.

Next Steps

Environment Variables

Configure advanced Umami features

Database Setup

Optimize your database configuration

Add Your Website

Start tracking your first website

Running in Production

Production deployment guide

Overview

Installation

Configuration

Docker Installation

Docker Installation

Prerequisites

Quick Start with Docker Compose

Using Pre-built Docker Image

Pull the Image

Run the Container

Configuration Options

Environment Variables

DATABASE_URL

APP_SECRET

PORT

BASE_PATH

Volume Mounts

Building from Source

Build Arguments

Management Commands

View Logs

Restart Containers

Stop and Remove

Updating Umami

Troubleshooting

Production Deployment

Next Steps

Environment Variables

Database Setup

Add Your Website

Running in Production

Build docs developers (and LLMs) love

Overview

Installation

Configuration

​Docker Installation

​Prerequisites

​Quick Start with Docker Compose

​Using Pre-built Docker Image

​Pull the Image

​Run the Container

​Configuration Options

​Environment Variables

DATABASE_URL

APP_SECRET

PORT

BASE_PATH

​Volume Mounts

​Building from Source

​Build Arguments

​Management Commands

​View Logs

​Restart Containers

​Stop and Remove

​Updating Umami

​Troubleshooting

​Production Deployment

​Next Steps

Environment Variables

Database Setup

Add Your Website

Running in Production

Build docs developers (and LLMs) love

Docker Installation

Prerequisites

Quick Start with Docker Compose

Using Pre-built Docker Image

Pull the Image

Run the Container

Configuration Options

Environment Variables

Volume Mounts

Building from Source

Build Arguments

Management Commands

View Logs

Restart Containers

Stop and Remove

Updating Umami

Troubleshooting

Production Deployment

Next Steps