my_geoip_server

What this is

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

What this repository contains

Binary / Asset	Description
geoip	Main GeoIP lookup server (Axum HTTP API)
update_db	Database updater — downloads the latest monthly DB-IP City Lite database
Dockerfile	Container image build
docker-compose.yml	Full stack with Prometheus and Grafana
Makefile	Build, Docker, and Compose helpers

Setup:

# Download the database
cargo run --bin update_db

# 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:

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

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.

Role in the stack

my_geoip_server provides IP-to-location resolution services within the Mycelium and Hero stack. Other services can query it to determine the geographic origin of traffic, apply region-based routing, or enrich observability data.

Relation to ThreeFold

This technology is used within the ThreeFold ecosystem and was first deployed on the ThreeFold Grid. The component itself is designed as reusable infrastructure technology and should be understood by its technical function first, independent of any specific deployment.

Ownership

This repository is owned and maintained by TF-Tech NV, a Belgian company responsible for the development and maintenance of this technology.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.