ip2location/mongodb repository overview

⁠docker-ip2location-mongodb

A ready-to-run MongoDB server preloaded with an IP2Location⁠ geolocation database. Supports the commercial packages and the free LITE⁠ package. Register for an account first as download token is required.

⁠Usage

docker network create ip2location-network

docker run --name ip2location \
  --network ip2location-network \
  -d \
  -e TOKEN={DOWNLOAD_TOKEN} \
  -e CODE={DOWNLOAD_CODE} \
  -e IP_TYPE=IPV4 \
  -e MONGODB_PASSWORD={MONGODB_PASSWORD} \
  ip2location/mongodb

docker logs -f ip2location      # Wait for "✓ Setup completed"

ENV Variables

CODE — LITE: DB1-LITE, DB3-LITE, DB5-LITE, DB9-LITE, DB11-LITE. Commercial: DB1 … DB26.

Only one address family is installed per container. To switch, start a fresh container with an empty /data/db — an existing install is not converted in place, and re-running with different settings prints a note explaining that.

The admin password is written to /config inside the container, so docker logs and docker exec access are equivalent to knowing it.

To start over:

docker rm -f ip2location
docker volume rm ip2location-data        # if you used -v ip2location-data:/data/db

⁠Query for IP Information

Two fields are stored: ip_to is the IP number and ip_to_index is the same number zero-padded to 40 characters and prefixed with A, which is what makes range comparison work as a string. Which one you filter on depends on the IP_TYPE you installed.

IPv4 — the IP number as a plain string:

use ip2location_database
db.ip2location_database.findOne( { ip_to: { $gte: "134744072" } } )

{ ip_to: "134874623", country_code: "US", country_name: "United States of America", ... }

IPv6 — the padded, A-prefixed form. For 2001:4860:4860::8888 the IP number is 42541956123769884636017138956568135816:

use ip2location_database
db.ip2location_database.findOne( { ip_to_index: { $gte: "A0042541956123769884636017138956568135816" } } )

Both search values are quoted strings. mongoimport --type csv imports every CSV value as text unless the field types are declared, so the unquoted form { ip_to: { $gte: 134744072 } } matches nothing and returns null — BSON compares across types by type order, and numbers sort before strings.

To convert an address to an IP number see the IP2Location FAQs⁠.

To store the numbers as int64 instead of strings, declare the types at import time with --columnsHaveTypes and int64(...); --columnsHaveTypes is only accepted together with --fields.

⁠Connect from an Application

Put your application on the same network and reach the container by name (ip2location):

docker run --network ip2location-network -t -i {YOUR_APPLICATION}

mongosh --host ip2location -u mongoAdmin -p {MONGODB_PASSWORD} --authenticationDatabase admin

⁠Update IP2Location Database

docker exec -it ip2location /update.sh

Imports a fresh copy and swaps it in with renameCollection(..., true), so queries keep working against the old data until the swap. The daily download quota is limited. If you get [QUOTA EXCEEDED] error, please try again after 24 hours.

⁠Articles and Tutorials

IP2Location Articles and Tutorials⁠