solar/umami-geoip.md

Umami GeoIP / Geo Stats Configuration

This project uses a self-hosted Umami instance for analytics. To enable geo-based statistics (countries/regions/cities), configure Umami with a local GeoIP database on the server where you run umami-docker-compose.yml.

1. Choose and install a GeoIP database

On the server where Docker runs:

1. Create a directory for GeoIP data, for example:

   sudo mkdir -p /opt/umami/geoip
   sudo chown "$(whoami)" /opt/umami/geoip
   

2. Obtain a GeoIP2 or compatible database file, for example MaxMind GeoLite2:

   • Create a MaxMind account and generate a license key.
   • Download the GeoLite2-City (or GeoLite2-Country) .mmdb file.
   • Place it at: /opt/umami/geoip/GeoLite2-City.mmdb

2. Mount GeoIP database into Umami container

Extend the umami service in umami-docker-compose.yml on the server:

  umami:
    # ...
    volumes:
      - /opt/umami/geoip:/geoip:ro
    environment:
      # Existing variables...
      DATABASE_URL: postgresql://${UMAMI_DB_USER:-umami}:${UMAMI_DB_PASSWORD}@umami-db:5432/${UMAMI_DB_NAME:-umami}
      APP_SECRET: ${UMAMI_APP_SECRET}
      DISABLE_TELEMETRY: "true"
      UMAMI_WEBSITE_URL: ${UMAMI_WEBSITE_URL:-https://analytics.example.com}
      # GeoIP-related environment variables may change between Umami versions,
      # so consult the official docs and set the appropriate variables to point
      # at /geoip/GeoLite2-City.mmdb.

Note: Umami's exact GeoIP configuration variables can change between releases. Check the official Umami documentation for the version you deploy and point it at /geoip/GeoLite2-City.mmdb inside the container.

3. Privacy and compliance notes

• The GeoIP database is stored locally on the analytics server; IP addresses are not sent to third-party APIs for lookup.
• Ensure your privacy policy explains that approximate geo location (e.g. country, region, city) is derived from IP addresses via a local GeoIP database and stored only in aggregate form in Umami.
• If required by your jurisdiction, enable appropriate consent mechanisms before loading the Umami tracking script on the frontend.