GeoIP Setup

Tally uses MaxMind's GeoLite2 City database to enrich sessions with country, region, and city data. This is optional — Tally works without it, but geo data won't be available.

Automatic setup (Docker)

If you set both MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY , the Docker entrypoint script will automatically download the GeoLite2 database on first start.

docker run -d   -e MAXMIND_ACCOUNT_ID=your-account-id   -e MAXMIND_LICENSE_KEY=your-license-key   -v tally-data:/app/data   tally:latest

The database is saved to /app/data/GeoLite2-City.mmdb (persisted via the volume).

Get a MaxMind license key

Sign up for a free MaxMind account
Go to Account Manage License Keys
Generate a new license key
Note your Account ID and License Key

Free tier: GeoLite2 is free for most use cases. MaxMind requires an account to download, but there's no charge for the GeoLite2 databases.

Manual setup

If you prefer to download the database manually:

# Download and extract
curl -fsSL "https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz"   -u "$ACCOUNT_ID:$LICENSE_KEY"   -o geolite2.tar.gz

tar -xzf geolite2.tar.gz
mv GeoLite2-City_*/GeoLite2-City.mmdb /app/data/

# Set the path (if non-default)
export GEOLITE2_PATH=/app/data/GeoLite2-City.mmdb

What you get

With GeoIP enabled, each session is enriched with:

Country — ISO country code (e.g., US, DE, JP)
Region — First-level administrative division (e.g., California, Bavaria)
City — City name
Latitude / Longitude — Approximate coordinates

This data appears in the Geo page of the dashboard and via the /api/v1/geo endpoint.

Updates

MaxMind publishes updates weekly. To update, either:

Restart the container (if auto-download is configured)
Manually download and replace the .mmdb file

The server loads the GeoIP database once at startup. A restart is required to pick up a new database file.