Umami

Last updated on 13 May 2025

I use Umami [1] for analytics on this website and a few other services that I run. I self-host Umami using Docker.

To start, create a `docker-compose.yml`:

services:

  umami:
    image: docker.umami.is/umami-software/umami:postgresql-latest
    environment:
      DATABASE_URL: postgresql://umami:CHANGEME@umamidb:5432/umami
      DATABASE_TYPE: postgresql
      HASH_SALT: CHANGEME
    depends_on:
      - umamidb
    restart: always
    expose:
      - 3000
    networks:
      - traefik_net
    labels:
      - traefik.http.routers.umami.rule=Host(`CHANGEME`)
      - traefik.http.routers.umami.tls=true
      - traefik.http.routers.umami.tls.certresolver=myresolver

  umamidb:
    image: postgres:12-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: CHANGEME
    volumes:
      - ./sql/schema.postgresql.sql:/docker-entrypoint-initdb.d/schema.postgresql.sql:ro
      - ./umami-data:/var/lib/postgresql/data
    restart: always
    networks:
      - traefik_net

networks:
  traefik_net:
    external: true

HTTPS

Since Umami must be publicly-accessible (so it can measure analytics on public websites), it must also be served over HTTPS.

The `docker-compose.yml` above puts the containers into the `traefik_net` network. See the Traefik [2] note for more information on setting this up.

Backing-up

Back-up Umami using the filesystem backups in the Backup [3] note.

Updating Umami

Recently I ran into trouble updating an old Umami instance to the latest version, which required manual migrations. However, the manual migration wouldn't work on the version I had running, and updating to the latest version caused crashes and restart cycles in the Docker container.

To fix the issue, I upgraded to an intermediate version, ran the migration script, and then continued to upgrade to the latest version:

1. Backup the Umami database files first

1. Stop the container (e.g. via Docker or Docker Compose)

1. Set the image to the intermediate version: `ghcr.io/umami-software/umami:postgresql-v1.40.0`

1. Start the container and exec into it

1. Run the upgrade script: `npx @umami/migrate-v1-v2@latest`

1. Exit from the container

1. Update the image to the new latest: `docker.umami.is/umami-software/umami:postgresql-latest`

1. Start the container