Umami User Guide: Exploring the Free and Open Source Website Analytics Solution

Umami is an open-source, privacy-focused alternative to Google Analytics. Umami provides powerful web analytics solutions without compromising user privacy.

Note: If the official website fails to load, please check whether your browser has ad-blockers or other related plugins enabled.

Getting Started with Umami Installation

Umami provides several installation methods:

• Install from source
• Build using Docker Compose
• Install via Docker image

The author recommends the latter two methods. If your server already has Docker installed, you can skip the Docker installation part.

Docker Installation

curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun
sudo systemctl start docker && sudo systemctl enable docker.service

# Domestic users may encounter network issues when pulling images, so it's recommended to change the mirror source. The steps are as follows:
vim /etc/docker/daemon.json

# Add the following content to the file:
{
  "registry-mirrors": [
    "https://docker.hpcloud.cloud",
    "https://docker.m.daocloud.io",
    "https://docker.unsee.tech",
    "https://docker.1panel.live",
    "http://mirrors.ustc.edu.cn",
    "https://docker.chenby.cn",
    "http://mirror.azure.cn",
    "https://dockerpull.org",
    "https://dockerhub.icu",
    "https://hub.rat.dev"
  ]
}

# Save and exit vim using :wq. If you're unfamiliar with vim, please refer to relevant documentation.
sudo systemctl restart docker

After Docker is installed, Docker Compose will also be installed.

Umami Docker Installation

Docker installation is very simple:

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

By default, port 3000 is used. Just make sure port 3000 is open.

Umami Docker Compose Installation

Docker Compose installation is mainly done by modifying the yml file for various configurations:

# Clone the necessary files from GitHub
git clone https://github.com/umami-software/umami.git
cd umami

# If you want to use the default configuration
docker compose up -d

For custom configurations, modify the docker-compose.yml file. Here’s an example:

version: '3'
services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: replace-me-with-a-random-string
    depends_on:
      db:
        condition: service_healthy
    restart: always
  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:

Run docker compose up -d and after a while, Umami will be successfully installed.

At this point, basic installation is complete. For more detailed parameters, click here.

Umami Source Installation

Source installation is also straightforward:

# First, install yarn
npm install -g yarn

# Clone the project
git clone https://github.com/umami-software/umami.git
cd umami

# Install dependencies
yarn install

# Create the environment configuration file .env
vim .env

Example environment configuration:

DATABASE_URL=mysql://username:mypassword@localhost:3306/umami
PORT=3006

Explanation:

• DATABASE_URL parameter format: mysql://username:password@host:port/database_name
• PORT is the service port (default is 3000, change it if there’s a conflict).
• If using PostgreSQL, change the protocol to postgresql.

Build and start:

yarn build
yarn start

It is recommended to use pm2 to manage the process:

sudo yarn global add pm2
pm2 start yarn --name umami -- start-env
pm2 startup
pm2 save

Summary:

• Docker installation is the easiest but requires higher performance.
• Source installation is more flexible and has lower resource usage.
• Choose the deployment method based on your actual needs.