Documentation

Configuring Apache2 and NGINX with MaxMind GeoIP2

An upcoming feature of the Joomla System - EU e-Privacy Directive plugin supports multiple location detection methods, ensuring compliance with GDPR and the EU e-Privacy Directive. For Joomla sites relying on caching (e.g., Varnish), integrating MaxMind’s GeoIP2 datasets with Apache2 or NGINX allows administrators to inject geolocation data into the Server-Timing HTTP header (e.g., Server-Timing: geo_eu;desc="1") post-cache. This server-side approach avoids client-side cookies, maintains cache efficiency, and enables the plugin to detect EU/EEA visitors for targeted consent banners.

Why Server-Timing?

The Server-Timing header is uniquely accessible to JavaScript via the Performance API, making it ideal for injecting geolocation data without altering cached content. This ensures fast, efficient, and privacy-compliant detection of EU visitors, with minimal performance overhead (~1-5ms).

This guide focuses on configuring MaxMind’s geoipupdate tool to maintain GeoLite2 databases and setting up Apache2 or NGINX to deliver the geo_eu metric in the Server-Timing header for the Joomla plugin. We assume a Linux environment (e.g., Ubuntu/Debian) and that you’ve followed MaxMind’s installation instructions.

Step 1: Install and Configure geoipupdate

The geoipupdate tool keeps MaxMind’s GeoLite2 databases up-to-date, providing the geolocation data needed for server-side lookups.

Prerequisites

  • Follow the official installation instructions for your distribution (e.g., sudo add-apt-repository ppa:maxmind/ppa && sudo apt update && sudo apt install geoipupdate for Ubuntu/Debian).
  • Register for a free MaxMind account at maxmind.com to obtain your Account ID and License Key.

Configuration

Edit /etc/GeoIP.conf (default location):

 
AccountID your_account_id
LicenseKey your_license_key
EditionIDs GeoLite2-Country
DatabaseDirectory /usr/share/GeoIP
 
 
  • Ensure the directory /usr/share/GeoIP/ exists: sudo mkdir -p /usr/share/GeoIP.
  • Test the setup: sudo geoipupdate -f /etc/GeoIP.conf. Verify the database at /usr/share/GeoIP/GeoLite2-Country.mmdb.
  • Automate updates with a cron job: Add to sudo crontab -e:
    0 2 * * 0 /usr/bin/geoipupdate -f /etc/GeoIP.conf

This runs weekly at 2 AM Sunday. Alternatively, if your package includes a systemd service, enable it: sudo systemctl enable geoipupdate.

Step 2: NGINX Configuration

NGINX uses the ngx_http_geoip2_module for GeoIP2 lookups and headers-more-nginx-module to set the Server-Timing header, injecting EU/EEA detection post-cache.

Prerequisites

  • Install required modules (Ubuntu/Debian example):
    sudo apt install libnginx-mod-http-geoip2 libnginx-mod-http-headers-more-filter
  • Ensure /usr/share/GeoIP/GeoLite2-Country.mmdb exists.
  • Restart NGINX: sudo systemctl restart nginx.

Configuration

Add the GeoIP2 configuration to the http block in /etc/nginx/nginx.conf or a separate file like /etc/nginx/conf.d/geoip2.conf:

http {
    geoip2 /usr/share/GeoIP/GeoLite2-Country.mmdb {
        auto_reload 24h;
        $geoip2_data_country_is_eu default=0 country is_in_european_union;
        $geoip2_data_country_iso country iso_code;  # Optional for debugging
    }
}

In your server block (e.g., /etc/nginx/sites-available/default), add:

server {
    listen 80;
    server_name example.com;

    add_header Server-Timing "remote_addr;desc=\"$remote_addr\",geo_eu;desc=\"$geoip2_data_country_is_eu\"";

    # Existing location blocks (e.g., proxy_pass or root)
    location / {
        # Your configuration here
    }
}

This sets geo_eu to 1 for EU/EEA countries (e.g., DE, FR) or 0 otherwise, with remote_addr for debugging. Test with:

curl -H "X-Real-IP: 141.52.0.0" -I https://your-domain.com

Expect: server-timing: remote_addr;desc="141.52.0.0",geo_eu;desc="1" (Germany). For a non-EU IP (e.g., 8.8.8.8), expect geo_eu;desc="0".

Step 3: Apache2 Configuration

Apache2 uses mod_maxminddb for GeoIP2 lookups and mod_headers to inject the Server-Timing header, compatible with cached responses.

Prerequisites

  • Install dependencies (Ubuntu/Debian):
    sudo apt install apache2 libmaxminddb-dev libapache2-mod-maxminddb
  • Enable modules: sudo a2enmod maxminddb headers && sudo systemctl restart apache2.
  • Verify /usr/share/GeoIP/GeoLite2-Country.mmdb exists.

Configuration

Add to your virtual host (e.g., /etc/apache2/sites-available/000-default.conf):

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /var/www/html

    # Enable MaxMind GeoIP2
    MaxMindDBEnable On
    MaxMindDBEnv GEOIP_COUNTRY_IS_EU default=0 country is_in_european_union /usr/share/GeoIP/GeoLite2-Country.mmdb
    MaxMindDBEnv GEOIP_COUNTRY_CODE country iso_code /usr/share/GeoIP/GeoLite2-Country.mmdb  # Optional for debugging

    # Add Server-Timing header
    <IfModule mod_headers.c>
        Header always append Server-Timing "remote_addr;desc=%{REMOTE_ADDR}e,geo_eu;desc=%{GEOIP_COUNTRY_IS_EU}e"
    </IfModule>

    # Existing <Directory> or proxy settings
</VirtualHost>

Test with:

curl -H "X-Forwarded-For: 141.52.0.0" -I https://your-domain.com

Expect: server-timing: remote_addr;desc="141.52.0.0",geo_eu;desc="1". For non-EU IPs (e.g., 8.8.8.8), expect geo_eu;desc="0".

Step 4: Testing and Joomla Configuration

Verify the Server-Timing header using:

  • Browser Dev Tools (Network > Headers) to inspect responses.
  • CLI: curl -I https://your-domain.com.

The header should appear as:

server-timing: remote_addr;desc="1.2.3.4",geo_eu;desc="0"

For EU IPs, geo_eu will be 1. Secure against IP spoofing in production by configuring your proxy or firewall to trust only valid X-Real-IP or X-Forwarded-For headers.

In the Joomla Administrator panel, configure the System - EU e-Privacy Directive plugin:

  • GeoIP: Set to Yes.
  • GeoIP Service: Set to Server Timing.

This enables the plugin to read geo_eu and apply EU-specific logic (e.g., consent banners for countries in the EU).

Best Practices

  • Caching: Place GeoIP2 lookups after cache layers (e.g., Varnish/CDN) to preserve cache hits.
  • Database Updates: Monitor /var/log/geoipupdate.log for errors. Ensure weekly updates via cron or systemd.
  • Security: Prevent header spoofing by validating client IPs at the proxy level.
  • Performance: GeoIP2 lookups are lightweight, but test with tools like ab or wrk for high-traffic sites.
  • Compliance: This cookie-free approach aligns with e-Privacy goals, but consult legal experts for full compliance.

For troubleshooting, refer to MaxMind’s documentation or server logs (/var/log/nginx/error.log or /var/log/apache2/error.log).