GeoIP Setup

Sparklytics uses MaxMind MMDB-format databases to enrich events with geographic data (country, city, region). This guide covers installation and configuration.

Overview

GeoIP enrichment is optional. If no database is configured:

Sparklytics continues to run normally
Geo fields (country, city, region) are stored as NULL
All other analytics features work unchanged

Docker images bundle a free DB-IP City Lite database — no setup needed for Docker users.

Quick Start (Docker)

Pre-Bundled Database

Official Sparklytics Docker images include DB-IP City Lite at /geoip/dbip-city-lite.mmdb.

docker run -d \
  --name sparklytics \
  -p 3000:3000 \
  -v sparklytics-data:/data \
  -e SPARKLYTICS_GEOIP_PATH=/geoip/dbip-city-lite.mmdb \
  sparklytics/sparklytics:latest

The bundled database is updated monthly. To use the latest version, follow the “Bare-Metal Install” steps below and mount it as a volume.

Bare-Metal Install

Option 1: DB-IP City Lite (Free, Recommended)

DB-IP City Lite is free, requires no registration, and is compatible with the MMDB format.

Download the database

Sparklytics includes a download script:

cd /path/to/sparklytics
./scripts/download-geoip.sh

This downloads the latest DB-IP City Lite MMDB to ./dbip-city-lite.mmdb (~50 MB).

The script tries the current month first, falling back to the previous month if not yet published.

Set environment variable

export SPARKLYTICS_GEOIP_PATH=./dbip-city-lite.mmdb

Or add to your .env file:

SPARKLYTICS_GEOIP_PATH=/var/lib/sparklytics/dbip-city-lite.mmdb

Start Sparklytics

SPARKLYTICS_DATA_DIR=./data \
SPARKLYTICS_GEOIP_PATH=./dbip-city-lite.mmdb \
./sparklytics

Check logs for confirmation:

[INFO] GeoIP database loaded: ./dbip-city-lite.mmdb

Attribution Requirement

DB-IP City Lite is licensed under Creative Commons Attribution 4.0.You must display: “IP geolocation by DB-IP” on any page showing geo data.

Manual Download

Alternatively, download directly:

wget https://download.db-ip.com/free/dbip-city-lite-$(date +%Y-%m).mmdb.gz
gunzip dbip-city-lite-*.mmdb.gz
mv dbip-city-lite-*.mmdb dbip-city-lite.mmdb

Option 2: MaxMind GeoLite2 City

MaxMind GeoLite2 is also free but requires account registration.

Create MaxMind account

Sign up at maxmind.com/en/geolite2/signup
Generate a license key in your account dashboard

Download GeoLite2-City.mmdb

# Replace YOUR_LICENSE_KEY with your actual key
wget "https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&license_key=YOUR_LICENSE_KEY&suffix=tar.gz" -O GeoLite2-City.tar.gz

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

Configure Sparklytics

export SPARKLYTICS_GEOIP_PATH=./GeoLite2-City.mmdb

MaxMind License Terms

MaxMind GeoLite2 requires attribution and has usage restrictions. See MaxMind’s license terms.

Configuration Reference

SPARKLYTICS_GEOIP_PATH

string

default:"./GeoLite2-City.mmdb"

Path to MaxMind MMDB-format GeoIP database file.Supported databases:

DB-IP City Lite (free, no registration)
MaxMind GeoLite2 City (free, requires account)
MaxMind GeoIP2 City (commercial)

# DB-IP (bare-metal)
SPARKLYTICS_GEOIP_PATH=./dbip-city-lite.mmdb

# DB-IP (Docker, bundled)
SPARKLYTICS_GEOIP_PATH=/geoip/dbip-city-lite.mmdb

# MaxMind GeoLite2
SPARKLYTICS_GEOIP_PATH=/path/to/GeoLite2-City.mmdb

What Happens if the File is Missing?

Sparklytics continues to run normally
A warning is logged at startup
Geo fields in events are set to NULL:
- country
- city
- region
All other analytics features (pageviews, sessions, referrers, etc.) work unchanged

Docker Volume Mounting

To use a custom GeoIP database with Docker:

# docker-compose.yml
version: '3.8'
services:
  sparklytics:
    image: sparklytics/sparklytics:latest
    ports:
      - "3000:3000"
    volumes:
      - sparklytics-data:/data
      - ./dbip-city-lite.mmdb:/geoip/custom-db.mmdb:ro
    environment:
      SPARKLYTICS_GEOIP_PATH: /geoip/custom-db.mmdb

volumes:
  sparklytics-data:

Mount as read-only (:ro) since Sparklytics only reads the file.

Updating the Database

GeoIP databases should be updated monthly for accurate data.

Docker (Bundled Database)

Pull the latest Sparklytics image:

docker pull sparklytics/sparklytics:latest
docker stop sparklytics
docker rm sparklytics
# Re-run docker run or docker-compose up

Bare-Metal

Download latest database

./scripts/download-geoip.sh

Or manually download from DB-IP or MaxMind.

Replace old file

mv dbip-city-lite.mmdb /var/lib/sparklytics/dbip-city-lite.mmdb

Restart Sparklytics

systemctl restart sparklytics
# Or if running manually:
# pkill sparklytics && ./sparklytics

Sparklytics reloads the database file on startup.

You do not need to restart Sparklytics immediately after updating the file. The old database remains in memory until the next restart.

Automated Updates

For production deployments, set up a monthly cron job:

# /etc/cron.monthly/update-geoip
#!/bin/bash
set -euo pipefail

cd /opt/sparklytics
./scripts/download-geoip.sh /var/lib/sparklytics/dbip-city-lite.mmdb
systemctl restart sparklytics

Make it executable:

chmod +x /etc/cron.monthly/update-geoip

Data Fields Enriched

When GeoIP is configured, these fields are populated on every event:

Field	Type	Example
`country`	ISO 3166-1 alpha-2	`US`, `GB`, `DE`
`city`	String	`San Francisco`, `London`
`region`	String	`California`, `England`

Accuracy depends on the database. City-level data is ~70-80% accurate. Country-level is ~95%+.

Privacy Considerations

Sparklytics does not store IP addresses. The GeoIP lookup happens in-memory during event ingestion:

Event arrives at /api/collect with IP from request headers
IP is hashed to generate a visitor_id (salted SHA-256)
IP is looked up in the MMDB to extract geo data
Geo fields are stored; IP is discarded
IP never touches the database

This design ensures compliance with privacy regulations (GDPR, CCPA) while still providing useful geographic insights.

Troubleshooting

”GeoIP database not found” Warning

[WARN] GeoIP database not found at ./GeoLite2-City.mmdb; geo fields will be NULL

Solution: Download a database and set SPARKLYTICS_GEOIP_PATH.

Geo Fields Are NULL Despite Configured Path

Check file permissions:

ls -l /path/to/database.mmdb
# Should be readable by the Sparklytics user
chmod 644 /path/to/database.mmdb

Verify path is correct:

# Check Sparklytics logs for loaded path
docker logs sparklytics | grep GeoIP

Test the MMDB file:

# Install mmdblookup (part of libmaxminddb)
apt-get install libmaxminddb-bin

# Test lookup
mmdblookup --file dbip-city-lite.mmdb --ip 8.8.8.8

Docker Container Can’t Find Mounted Database

# Check volume is mounted
docker exec sparklytics ls -l /geoip/

# Verify environment variable inside container
docker exec sparklytics printenv | grep GEOIP

If empty, ensure the volume mount and env var are in docker-compose.yml or docker run command.

Database Comparison

Database	License	Registration	Size	Accuracy
DB-IP City Lite	CC BY 4.0	No	~50 MB	Good
MaxMind GeoLite2	Custom	Yes (free)	~70 MB	Very Good
MaxMind GeoIP2 City	Commercial	Yes (paid)	~100 MB	Excellent

Recommendation: Use DB-IP City Lite for most self-hosted deployments. Upgrade to MaxMind if you need higher accuracy.

Get Started

Core Features

Integrations

Configuration

Self-Hosting

Overview

Quick Start (Docker)

Pre-Bundled Database

Bare-Metal Install

Option 1: DB-IP City Lite (Free, Recommended)

Attribution Requirement

Manual Download

Option 2: MaxMind GeoLite2 City

MaxMind License Terms

Configuration Reference

What Happens if the File is Missing?

Docker Volume Mounting

Updating the Database

Docker (Bundled Database)

Bare-Metal

Automated Updates

Data Fields Enriched

Privacy Considerations

Troubleshooting

”GeoIP database not found” Warning

Geo Fields Are NULL Despite Configured Path

Docker Container Can’t Find Mounted Database

Database Comparison

See Also

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Configuration

Self-Hosting

​Overview

​Quick Start (Docker)

​Pre-Bundled Database

​Bare-Metal Install

​Option 1: DB-IP City Lite (Free, Recommended)

​Attribution Requirement

​Manual Download

​Option 2: MaxMind GeoLite2 City

​MaxMind License Terms

​Configuration Reference

​What Happens if the File is Missing?

​Docker Volume Mounting

​Updating the Database

​Docker (Bundled Database)

​Bare-Metal

​Automated Updates

​Data Fields Enriched

​Privacy Considerations

​Troubleshooting

​”GeoIP database not found” Warning

​Geo Fields Are NULL Despite Configured Path

​Docker Container Can’t Find Mounted Database

​Database Comparison

​See Also

Build docs developers (and LLMs) love

Overview

Quick Start (Docker)

Pre-Bundled Database

Bare-Metal Install

Option 1: DB-IP City Lite (Free, Recommended)

Attribution Requirement

Manual Download

Option 2: MaxMind GeoLite2 City

MaxMind License Terms

Configuration Reference

What Happens if the File is Missing?

Docker Volume Mounting

Updating the Database

Docker (Bundled Database)

Bare-Metal

Automated Updates

Data Fields Enriched

Privacy Considerations

Troubleshooting

”GeoIP database not found” Warning

Geo Fields Are NULL Despite Configured Path

Docker Container Can’t Find Mounted Database

Database Comparison

See Also