letstool/http2geoip repository overview

⁠http2geoip

Lightweight HTTP gateway that geolocates IP addresses through a JSON REST API.

Send a POST /api/v1/geoip request, get geographic data back as structured JSON. Supports single and batch IP lookups (IPv4 and IPv6), with localized country and continent names in 7 languages. The database is downloaded from MaxMind on startup and refreshed daily — or synced from another http2geoip instance in peer mode.

The binary embeds a web UI (dark/light mode, 15 languages) and an OpenAPI 3.1 spec — no external files, no runtime dependencies beyond the mmdb database.

⁠Quick start

docker run -p 8080:8080 \
  -v ./db:/data \
  -e GEOIP_DB_URL="https://<user>:<license_key>@download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz" \
  letstool/http2geoip:latest

Open http://localhost:8080⁠ to use the web UI, or query the API directly:

curl -s -X POST http://localhost:8080/api/v1/geoip \
  -H "Content-Type: application/json" \
  -d '{"ip":"8.8.8.8","lang":"en"}' | jq

⁠Configuration

CLI flags take priority over environment variables.

docker run -p 8080:8080 \
  -v ./db:/data \
  -e GEOIP_DB_URL="https://<user>:<key>@download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz" \
  -e GEOIP_LISTEN_ADDR=0.0.0.0:8080 \
  -e GEOIP_UPDATE_HOUR=03:00 \
  -e GEOIP_MAX_IPS=500 \
  letstool/http2geoip:latest

⁠Peer mode

If you already have a running http2geoip instance, other containers can sync their database from it directly — no MaxMind account required on the peers:

docker run -p 8080:8080 \
  -e GEOIP_DB_URL=http://primary-geoip-host:8080 \
  letstool/http2geoip:latest

⁠Repo

https://github.com/letstool/http2geoip⁠

⁠License

This project is licensed under the Apache License, Version 2.0⁠.

Copyright (c) 2026 letstool.net

⁠See also