GeoIP2 + Nginx + Debian: A Practical Setup Guide

I’ve been working with GeoIP2 and Nginx on Debian for the past few years on personal projects. I wrote some time ago about Compiling, Installing and Configuring the GeoIP2 module, which gives you access to the latest code changes but requires recompilation with every Nginx version update.

However, if you’re comfortable with Debian’s default packages (typically a couple of versions behind upstream), you can leverage the standard tooling already developed by MaxMind. This approach is significantly more maintainable for production environments.

This guide will walk you through installing and configuring the GeoIP2 modules for Nginx using Debian’s package system. For the actual Nginx configuration examples, refer to my previous post on GeoIP2 Nginx configuration.

Prerequisites

Before we begin, ensure you have:

• A Debian server running Debian 13 (Trixie) or later. Some of the tools mentioned here are only available in recent Debian releases. If you’re on Debian 12 (Bookworm) or earlier, some packages may need to be installed from backports or compiled manually.
• MaxMind account credentials from an active account at maxmind.com:
  • AccountID: Found in your profile under “Account Information”
  • LicenseKey: Found under “Manage License Keys”

Required Packages

We’ll be installing the following packages:

• mmdb-bin - Command line utilities to resolve IPs using the libmaxminddb library
• libmaxminddb0 - The core C library for reading MaxMind DB files (GeoIP2 databases)
• libmaxminddb-dev - Development headers for the MaxMind library (useful for future extensions)
• geoipupdate - Automated update tool for GeoIP2 and GeoLite2 databases (from contrib repository)
• libnginx-mod-stream-geoip2 - Nginx stream module for GeoIP2 lookups (for TCP/UDP streams)
• libnginx-mod-http-geoip2 - Nginx HTTP module for GeoIP2 lookups (for web traffic)

Installation Steps

1. Install the Required Packages

Update your package repositories and install the necessary components:

# Update package lists
sudo apt update

# Install MaxMind libraries and tools
sudo apt install mmdb-bin geoipupdate libmaxminddb0 libmaxminddb-dev

# Install Nginx GeoIP2 modules
sudo apt install libnginx-mod-stream-geoip2 libnginx-mod-http-geoip2

2. Configure GeoIP Update

Create or update the configuration file /etc/GeoIP.conf with your MaxMind credentials:

# Your MaxMind account credentials
AccountID 123456
LicenseKey your_license_key_here

# Database editions to download
EditionIDs GeoLite2-Country GeoLite2-City GeoLite2-ASN

This configuration will download all three free GeoLite2 databases. You can customize additional parameters like download directory and proxy settings - see the official GeoIP Update documentation for all available options.

3. Download the Databases

Run the update tool manually to download the initial database files:

# Run with verbose output to see download progress
# Requires sudo as it writes to /usr/share/GeoIP
sudo geoipupdate -v

After completion, verify the downloaded files:

ls -lh /usr/share/GeoIP

You should see output similar to:

-rw-r--r-- 1 root root  11M Jan  2 10:52 GeoLite2-ASN.mmdb
-rw-r--r-- 1 root root  61M Jan  2 10:52 GeoLite2-City.mmdb
-rw-r--r-- 1 root root 9.3M Jan  2 10:52 GeoLite2-Country.mmdb

4. Update Nginx Configuration

In your nginx.conf (typically in /etc/nginx/nginx.conf), update the database paths to point to the new location:

# Change from your old custom path
# geoip2 /etc/nginx/geolite2db/GeoLite2-City.mmdb

# To the standard Debian location
geoip2 /usr/share/GeoIP/GeoLite2-City.mmdb {
    # Your GeoIP2 variable definitions here
}

Test the Nginx configuration and restart:

# Test configuration syntax
sudo nginx -t

# Restart Nginx to apply changes
sudo systemctl restart nginx

That’s it! Your Nginx instance should now be using the MaxMind databases from the standard system location.

Optional Optimizations

Reduce Database Downloads

If you don’t need all three database editions, you can optimize by downloading only what you use. Edit /etc/GeoIP.conf and modify the EditionIDs line:

# Example: Only download the City database
EditionIDs GeoLite2-City

This reduces download time and disk space usage. The City database includes country-level data, so if you’re using City, you typically don’t need the separate Country or ASN database.

Automate Database Updates

MaxMind releases updated databases on Tuesdays and Fridays (MaxMind update-schedule). Set up a cron job to automatically keep your databases current:

# Edit your crontab
crontab -e

Add one of the following entries:

Basic version (runs silently):

# Run at 2:46 AM every Wednesday and Saturday
# Format: minute hour day month day-of-week command
46 2 * * 3,6 /usr/bin/geoipupdate

With logging (recommended for troubleshooting):

# Run at 2:46 AM every Wednesday and Saturday with logging
46 2 * * 3,6 /usr/bin/geoipupdate -v >> /var/log/geoipupdate.log 2>&1

Cron schedule breakdown:

• 46 - Minute (46)
• 2 - Hour (2 AM)
• * - Any day of month
• * - Any month
• 3,6 - Days of week (Wednesday=3, Saturday=6)

I schedule updates for Wednesday and Saturday mornings to catch the Tuesday and Friday releases respectively. The specific time of 2:46 AM is just my preference to avoid peak hours - adjust to whatever works for your maintenance window.

Log Rotation

If you’re logging updates, consider setting up log rotation to prevent unbounded growth:

# Create a logrotate configuration
sudo nano /etc/logrotate.d/geoipupdate

/var/log/geoipupdate.log {
    weekly
    rotate 4
    compress
    missingok
    notifempty
}

Testing Your Setup

Verify the installation with a quick IP lookup:

# Test with a known IP address
mmdblookup --file /usr/share/GeoIP/GeoLite2-City.mmdb --ip 8.8.8.8

You should see detailed geographic information for the queried IP.

Additional Resources

When working with GeoIP data, I’ve found this comparison chart helpful for understanding the differences between database editions and what data each provides:

MaxMind GeoIP Databases Comparison Chart (PDF)

For comprehensive documentation:

• MaxMind Database Update Documentation
• Database Update Schedule
• Nginx GeoIP2 Module Documentation
• mmdbinspect - github repo

If you encounter any issues or have questions, feel free to reach out!