Self hosting Umami Analytics

Introduction

Umami is a simple, lightweight, privacy focused alternative to Google Analytics. It is known for ease of use, cookie-free tracking, GDPR compliant analytics software.

It is free and open source, you can use their platform for hobby projects as they have a generous free tier. You can self host it in your server for free.

In this tutorial I will guide you through the steps to install and configure Umami on Debian 12, setup Umami and use Caddy to automatically reverse proxy and generate an SSL certificate.

Steps

Step 1: Pre-requisites

You need docker installed on the vps as we will use the docker to install Umami. You can follow the instuctions on the docker’s official website.

You also need caddy installed in your system and can follow the instructions on Caddy’s website.

Check and update all other applications using the following.

sudo apt update
sudo apt upgrade

Step 2: Installing Umami

Now we have Docker and Caddy installed on our system we use the following command to pull the Umami Git repository and then movie into the pulled directory.

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

Now we needs to make to adjustments to the Umami docker compose file. First, run the following command to generate a random string of characters, then copy it into the APP_SECRET in the file.

openssl rand -base64 32

Second change the ports to 127.0.0.1:3000:3000 in the file, it is to enhance security and ensure all traffic goes through your reverse proxy (Caddy).

1
services:
2
  umami:
3
    image: ghcr.io/umami-software/umami:postgresql-latest
4
    ports:
5
      - "127.0.0.1:3000:3000"
6
    environment:
7
      DATABASE_URL: postgresql://umami:umami@db:5432/umami
8
      DATABASE_TYPE: postgresql
9
      APP_SECRET: "paste your app secret here"
10
    depends_on:
11
      db:
12
        condition: service_healthy
13
    init: true
14
    restart: always
15
    healthcheck:
16
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
17
      interval: 5s
18
      timeout: 5s
19
      retries: 5
20
  db:
21
    image: postgres:15-alpine
22
    environment:
23
      POSTGRES_DB: umami
24
      POSTGRES_USER: umami
25
      POSTGRES_PASSWORD: umami
26
    volumes:
27
      - umami-db-data:/var/lib/postgresql/data
28
    restart: always
29
    healthcheck:
30
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
31
      interval: 5s
32
      timeout: 5s
33
      retries: 5
34
volumes:
35
  umami-db-data:

If port 3000 is being used by some other application, then you need to change the port in the docker compose file and CaddyFile.

Step 3: Configuring Caddy

After setting up Umami, we must configure Caddy.

Use the following command to open the CaddyFile

sudo nano /etc/caddy/Caddyfile

Clear out the default contents and paste the following in the file. Replace umami.domain.com with your actual domain.

umami.domain.com {
        reverse_proxy localhost:3000
}

Save and restart Caddy service using the following command.

sudo systemctl restart caddy

Step 4: Start Umami

After configuring Caddy, move into your Umami directory. Start Umami using the following command.

sudo docker compose up -d

This will pull the necessary images, start the containers in the background, and set Umami up and running at port 3000.

You can check if everything is running properly using

sudo docker ps -a

This will list all running containers. You should see both the umami and umami-db services listed and marked as Up.

You can now access Umami through your domain specified in CaddyFile.

umami.domain.com

Log in using the default credentials

• Username: admin
• Password: umami

Before doing anything else, I strongly advise creating/ changing the admin username to something unique and change the a strong password. You can also create a new admin and delete the default one.

Update

To update your Umami installation, simply pull the latest files from Github using

git pull

After downloading the updated files. Simply restart docker.

docker compose down

Followed by.

docker compose up -d

Conclusion

With this, your Umami instance is now fully deployed and secured behind a reverse proxy, you have control over your analytics.

From here, you can start adding websites, creating new users, setting up custom events.

If you run any issues or need further help, fell free to reach out via email or open a discussion