issaali/ip-lookup repository overview

A simple and efficient Go-based HTTP service that provides geolocation information for IP addresses using the MaxMind GeoLite2-City database.

The ip-lookup Docker container expects the GeoLite2 database to be available at /geoipdb/GeoLite2-City.mmdb by default. This path is configurable via the GEOIP_DB_PATH environment variable if needed.

The recommended way to run this service with Docker is by using docker-compose along with MaxMind's official geoipupdate container. This automates the download and periodic refresh of the GeoLite2 database, which the ip-lookup service will then use.

Here’s how to set it up:

1. Create a docker-compose.yml file:

   version: "3.8"
   
   services:
     geoipupdate:
       container_name: geoipupdate
       image: ghcr.io/maxmind/geoipupdate
       restart: unless-stopped
       environment:
         # Replace with your actual MaxMind account ID and license key
         - GEOIPUPDATE_ACCOUNT_ID=YOUR_ACCOUNT_ID
         - GEOIPUPDATE_LICENSE_KEY=YOUR_LICENSE_KEY
         - GEOIPUPDATE_EDITION_IDS=GeoLite2-City # We only need the City database
         - GEOIPUPDATE_FREQUENCY=72 # How often to check for updates (in hours)
       volumes:
         - geoip_data:/usr/share/GeoIP # geoipupdate writes here
   
     ip-lookup:
       container_name: ip-lookup
       image: issaali/ip-lookup:latest # Or a specific version
       restart: unless-stopped
       depends_on:
         - geoipupdate
       ports:
         - "8080:8080" # Map host port 8080 to container port 8080
       volumes:
         - geoip_data:/geoipdb # ip-lookup reads from here
       environment:
         # GEOIP_DB_PATH is already set to /geoipdb/GeoLite2-City.mmdb in the Dockerfile
         # LISTEN_ADDR can be overridden here if needed, e.g., - LISTEN_ADDR=:9000
         - LISTEN_ADDR=:8080
         # ALLOWED_CORS_ORIGINS can be set here to configure allowed origins for CORS
         # Example: - ALLOWED_CORS_ORIGINS=http://localhost:3000,https://your.frontend.app
         # Example to allow all: - ALLOWED_CORS_ORIGINS=*
       # Add healthcheck if desired
       # healthcheck:
       #   test: ["CMD", "curl", "-f", "http://localhost:8080/healthz"]
       #   interval: 30s
       #   timeout: 10s
       #   retries: 3
   
   volumes:
     geoip_data: # This named volume is shared between the two services
       driver: local
   

   Copy

2. Sign up for a MaxMind Account: You need a MaxMind account and a license key to use geoipupdate. You can typically get these from the MaxMind website⁠. The free GeoLite2 databases require account signup.

3. Configure Environment Variables: Replace YOUR_ACCOUNT_ID and YOUR_LICENSE_KEY in the docker-compose.yml file with your actual MaxMind credentials. Alternatively, you can use a .env file in the same directory as your docker-compose.yml:

   GEOIPUPDATE_ACCOUNT_ID=YOUR_ACCOUNT_ID
   GEOIPUPDATE_LICENSE_KEY=YOUR_LICENSE_KEY
   

   Copy

   And then reference them in docker-compose.yml:

   # ... inside geoipupdate service environment:
   - GEOIPUPDATE_ACCOUNT_ID=${GEOIPUPDATE_ACCOUNT_ID}
   - GEOIPUPDATE_LICENSE_KEY=${GEOIPUPDATE_LICENSE_KEY}
   # ...
   

   Copy

4. Run Docker Compose:

   docker-compose up -d
   

   Copy

   This will start both services. The geoipupdate service will download the GeoLite2-City.mmdb into the shared geoip_data volume, and ip-lookup will read it from there.