GeoIP & Geographic Access Control

QuoteNode includes optional geographic access control and country-level tracking using the MaxMind GeoLite2 database.

Two Uses of GeoIP

1. Application access control

When enabled, the GeoIP filter can restrict application access to specific countries. Requests from disallowed countries receive HTTP 403 (Forbidden).

This is useful for organizations that:

• Operate only within specific jurisdictions
• Want to reduce exposure to automated attacks from certain regions
• Must comply with data residency or access control regulations

2. Offer interaction tracking

When a client opens a public offer link, the system records the client’s country code (ISO 3166-1 alpha-2) alongside the interaction event. This provides geographic context for offer analytics:

• “Your offer was opened from Germany” — confirms international reach
• “Multiple opens from different countries” — may indicate the offer was forwarded

How It Works

Database

GeoIP resolution uses the MaxMind GeoLite2-Country database — a local file (.mmdb format), not an external API. All lookups happen in memory with no network calls.

The database file must be downloaded separately (MaxMind requires a free account for GeoLite2 access) and mounted into the container at the configured path.

IP Detection

The system identifies client IPs in this order:

1. X-Real-IP header — set by the reverse proxy (most reliable)
2. X-Forwarded-For header — first address in the chain
3. request.getRemoteAddr() — direct connection fallback

Proper reverse proxy configuration (Caddy, Nginx, or Coolify’s proxy) is important for accurate IP detection.

Public offer exemption

Public offer endpoints (/offer/public/*) are always exempt from geographic restrictions. This ensures that clients can view and respond to offers regardless of their location, even when the application itself is geo-restricted.

Configuration

Variable	Default	Description
GEOIP_ENABLED	false	Enable/disable GeoIP functionality
geoip.db-path	—	Path to the MaxMind .mmdb database file
geoip.allowed-countries	(empty)	Comma-separated ISO country codes (e.g., PL,DE,FR). Empty = no restriction

When geoip.allowed-countries is empty, the GeoIP filter is passive — it resolves country codes for tracking purposes but does not block any requests.

Privacy Considerations

• GeoIP resolution is stateless — no IP-to-country mapping is stored permanently.
• For offer tracking, only the country code is recorded (e.g., “PL”), not the IP address itself.
• IP addresses recorded in offer web events are subject to the configurable IP anonymization job, which hashes them after a configurable number of days for GDPR compliance.