GeoIP

A lightweight GeoIP lookup server built with Rust and Axum. Uses the DB-IP City Lite database to resolve IP addresses to geographic information.

Features

• IP geolocation via query parameter, X-Real-IP header, or connection address
• JSON API response with continent, country, state/province, city, and coordinates
• Rate limiting per client IP (sliding window)
• Prometheus metrics (/metrics) and health check (/health) endpoints
• Pre-configured Grafana dashboard via Docker Compose
• Separate binary to update the database

Setup

Download the database

cargo run --bin update_db

This downloads the latest monthly DB-IP City Lite database and saves it as dpip-city.mmdb.

Run the server

cargo run --bin geoip

The server starts on port 8080 by default.

Docker

make docker-build
make docker-run

This builds the image and runs it, mounting your local dpip-city.mmdb into the container.

Docker Compose (with Prometheus & Grafana)

make up

This starts the geoip server, Prometheus, and Grafana together. Once running:

• GeoIP API: http://localhost:8080
• Grafana dashboards: http://localhost:3000 (default credentials: admin/admin)
• Metrics endpoint: http://localhost:8080/metrics
• Health check: http://localhost:8080/health

To stop:

make down

To follow logs:

make logs

API

GET /?ip=<address>

Returns geolocation data for the given IP address.

IP resolution order:

1. ?ip= query parameter
2. X-Real-IP header
3. Client connection address

Example:

curl "http://localhost:8080/?ip=8.8.8.8"

Response:

{
  "continent_code": "NA",
  "continent_name": "North America",
  "country_code": "US",
  "country_eu": false,
  "country_name": "United States",
  "state_province": "California",
  "city": "Mountain View",
  "latitude": 37.386,
  "longitude": -122.0838,
  "source": "dpip"
}

Releasing

Prerequisites

1. Create a Forgejo API token at Settings > Applications with write permissions
2. Add it as a repo secret named FORGEJO_TOKEN at Settings > Secrets

Create a release

Tag and push:

git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0

This triggers the release workflow which builds the binary and uploads it to Forgejo releases.