nschermer/geo-guardian repository overview

⁠Quick reference

Where to get help: GitHub⁠

⁠🛡️ Geo Guardian

A high-performance GeoIP-based access control service written in Go.

This container is intended for use as a ForwardAuth middleware in Traefik, enabling geo-location based access control for your applications. See Traefik ForwardAuth documentation⁠ for integration details.

⁠🎯 Overview

This service provides IP-based access control using GeoIP lookups and local IP allowlisting. It checks incoming requests against:

1. Local IP ranges (configurable)
2. Country codes (configurable)

Requests are allowed, or blocked, if they match either criteria.

⁠✨ Why Geo Guardian?

⁠🚀 Easier Than Nginx + GeoIP2

• No compilation hassles - Pre-built Docker containers ready to use
• Nginx with GeoIP2 module requires custom builds or hard-to-find pre-built images
• Drop-in solution without complex module compilation

⁠🎛️ Simpler Than Traefik GeoIP Plugins

• Straightforward configuration with environment variables
• No complex plugin installation or middleware chain configuration
• Clean integration via ForwardAuth middleware

⁠🔄 Automated Database Updates

• Easy to keep up-to-date using MaxMind's official update tools
• Automatic database reload every 15 minutes (no restarts needed)
• Compatible with MaxMind's geoipupdate utility

⁠📊 Built-in Observability

• Native Prometheus metrics for Grafana integration
• Per-country, per-host statistics out of the box
• Cache performance monitoring included
• No additional plugins or exporters needed

⁠🎁 Features

• ⚡ Fast GeoIP lookups with intelligent caching (1000 entries)
• 🔄 Hot database reloads without restarts (every 15 minutes)
• 🔒 Thread-safe concurrent request handling
• 💾 Minimal footprint (~15MB Alpine-based container)
• 🌐 EU support with single flag for all European Union countries
• 📈 Prometheus metrics for monitoring and alerting
• 🎨 Flexible blocking - allowlist or blocklist modes

⁠🗄️ GeoIP Database

This service is designed to run with the free MaxMind GeoLite2 Country database. Download and update instructions are available in MaxMind's documentation: https://support.maxmind.com/knowledge-base/articles/download-and-update-maxmind-databases⁠ You will need a (free) MaxMind account to obtain an account ID and license key before downloading the database.

⁠⚙️ Environment Variables

• GEOIP2_DB (required): Path to GeoIP2 database file (e.g., /data/GeoLite2-Country.mmdb)
• HOST_ADDR (optional): Server host address to listen on
  • Default: :80
• LOCAL_IPS (optional): Comma-separated list of local IP ranges in CIDR notation
  • Default: 192.168.0.0/16,10.0.0.0/8,127.0.0.0/8
• ACCEPT_COUNTRY_CODES (optional): Comma-separated list of allowed country codes (ISO 3166-1 alpha-2)
  • Example: US,CA,GB,DE
• ACCEPT_EUROPEAN_UNION (optional): When set to a truthy value (true, 1, yes), allows any country flagged as part of the EU by GeoIP (IsInEuropeanUnion)
• BLOCK_COUNTRY_CODES (optional): Comma-separated list of blocked country codes (ISO 3166-1 alpha-2)
  • Example: CN,RU,US
  • Cannot be used with ACCEPT_COUNTRY_CODES or ACCEPT_EUROPEAN_UNION (mutually exclusive)
• VERBOSE (optional): Enables verbose logging of allowed and blocked requests
  • Default: false

⁠Compose

volumes:
  geoipupdate_data: {}

services:
  traefik:
    image: traefik:latest
    container_name: traefik_app
    restart: unless-stopped
    networks:
      - default
    labels:
      traefik.http.middlewares.geoguardian.forwardauth.address: http://geoguardian/

  geoipupdate:
    container_name: "geoipupdate"
    image: ghcr.io/maxmind/geoipupdate:latest
    restart: unless-stopped
    environment:
      GEOIPUPDATE_ACCOUNT_ID: YOUR_ACCOUNT_ID
      GEOIPUPDATE_LICENSE_KEY: YOUR_LICENSE_KEY
      GEOIPUPDATE_EDITION_IDS: GeoLite2-Country
      GEOIPUPDATE_FREQUENCY: 72
    volumes:
      - "geoipupdate_data:/usr/share/GeoIP"

  geoguardian:
    container_name: geoguardian
    image: nschermer/geo-guardian:latest
    restart: unless-stopped
    ports:
      - "8080:80" # only needed if you want to collect or see metrics
    networks:
      - default
    environment:
      GEOIP2_DB: /usr/share/GeoIP/GeoLite2-Country.mmdb
      ACCEPT_COUNTRY_CODES: NL,BE,LU
    volumes:
      - "geoipupdate_data:/usr/share/GeoIP:ro"