Documentation Index
Fetch the complete documentation index at: https://mintlify.com/msimerson/maxmind-geolite-mirror/llms.txt
Use this file to discover all available pages before exploring further.
maxmind-geolite-mirror is a lightweight Node.js CLI tool that fetches MaxMind’s GeoLite2 IP geolocation databases directly to your server and keeps them current over time. Rather than manually downloading database files through a web interface, you run a single command — or automate it on a schedule — and the tool handles authentication, conditional downloading, and file extraction for all three GeoLite2 databases at once. Because downloads only happen when a newer version is available on MaxMind’s servers, repeated runs are fast and network-efficient by design.
A free MaxMind account is required to download GeoLite2 databases. Sign up at maxmind.com to obtain a license key. Once registered, generate a license key in your account portal and set it as the
MAXMIND_LICENSE_KEY environment variable before running the tool.What gets mirrored
The tool downloads the three current GeoLite2 binary database files in MaxMind DB (.mmdb) format:
| File | Contents |
|---|---|
GeoLite2-Country.mmdb | Maps IP addresses to ISO country codes and country names |
GeoLite2-City.mmdb | Maps IP addresses to city, subdivision, country, and postal data |
GeoLite2-ASN.mmdb | Maps IP addresses to Autonomous System Numbers and organization names |
/usr/local/share/GeoIP/) and can be read by any MaxMind-compatible library.
Conditional downloads with If-Modified-Since
For each database, the tool first checks whether a local copy already exists. If it does, a lightweight HEAD request is sent to MaxMind’s download server with an If-Modified-Since header populated from the local file’s modification timestamp. If the server responds with 304 Not Modified, the local copy is already current and no download occurs. Only when the server returns 200 OK — meaning the remote file is newer — does the tool proceed to fetch and extract the database. If no local copy exists yet, the tool skips the HEAD check and downloads immediately. This means running the tool daily or weekly has negligible network overhead once the databases are established.
Zero-dependency design
The tool is built entirely on Node.js built-in modules —https, fs, zlib, path, and url — with no runtime npm dependencies to install or keep up to date. This keeps the package small, auditable, and suitable for locked-down server environments where third-party dependencies are a concern. The one optional dependency, tar-stream, is listed under optionalDependencies and is only required for tarball extraction during database downloads. If tar-stream is not installed, the tool will report an error when it attempts to extract a .tar.gz response.
Explore the docs
Quickstart
Install the CLI, set your license key, and download your first databases in under five minutes.
License Key Configuration
Learn how to configure your MaxMind license key via environment variable or config file.
Running the Mirror
Understand command output, error handling, and how to mirror databases on demand.
Scheduling
Set up a cron job or systemd timer to keep your databases automatically up-to-date.