GeoIP Database Setup
Relevant source files
The following files were used as context for generating this wiki page:
Glimpse utilizes IP-based geolocation to power its real-time user mapping and traffic visualization features. The system relies on the MaxMind GeoLite2 database to resolve client IP addresses into geographic metadata, including country, region, city, and coordinates. This data is critical for the "Live Map" feature, which allows administrators to see where users are located globally as events occur.
Sources: README.md:1-15, PROJECT_OUTLINE.md:1-10
Configuration and Installation
The GeoIP system requires a MaxMind GeoLite2 license key, which can be obtained for free from MaxMind. This key is used during the installation process to download and update the local geolocation binary database.
Environment Setup
The project requires the GEOLITE_LICENSE_KEY environment variable to be defined in the root .env file or within the Docker environment configuration.
| Variable Name | Description | Required |
|---|---|---|
GEOLITE_LICENSE_KEY | Your MaxMind GeoLite2 License Key | Yes |
Sources: README.md:38-48, docker/docker-compose.yml:8
Database Update Procedure
For standalone installations, the database must be manually updated after installing dependencies. The project uses the geoip-lite library, which provides a script to fetch the latest MaxMind data.
# Update GeoIP database with your MaxMind license key
cd node_modules/geoip-lite && npm run updatedb license_key=YOUR_MAXMIND_LICENSE_KEY
cd ../..
Sources: README.md:105-107, README.md:155-160
Architecture and Data Flow
The geolocation lookup occurs asynchronously within the background worker system to prevent blocking the main API event ingestion.
Geolocation Lookup Process
When an event is ingested, the eventWorker extracts the IP address from the event metadata and passes it to the geoLookupIp utility.
The diagram above shows how IP addresses are processed through the cache and the local database to retrieve geographic information.
Sources: app/workers/eventWorker.ts:88-105, app/workers/lib/geolookupIp.ts:37-54
Caching Strategy
To optimize performance and reduce repeated lookups for the same IP address, Glimpse implements an in-memory LRU (Least Recently Used) cache.
- Cache Capacity: 20,000 entries.
- TTL (Time To Live): 1 hour (3,600,000 ms).
- Key Format:
geoip-{ipAddress}.
Sources: app/workers/lib/lru.ts:4-7, app/workers/lib/geolookupIp.ts:38-40
Data Structures
The system normalizes raw data from the geoip-lite library into a standard GeoResult type used throughout the worker service.
GeoResult Schema
| Field | Type | Description |
|---|---|---|
country | string | ISO 3166-1 alpha-2 country code |
region | string | Region or state code |
city | string | City name |
timezone | string | Timezone string (e.g., "America/New_York") |
lat | number | Latitude coordinate |
lon | number | Longitude coordinate |
Sources: app/workers/lib/geolookupIp.ts:4-11, app/workers/lib/geolookupIp.ts:25-30
Database Persistence
Geographic data is persisted in two locations:
- Redis: Stored in a hash set for the active session (e.g.,
session:projectId:sessionId) with a 300-second TTL. - PostgreSQL: Stored in the
eventstable via a buffered batch insert process.
Sources: app/workers/eventWorker.ts:54-61, app/workers/eventWorker.ts:111-120
Summary
GeoIP Database Setup in Glimpse is a hybrid system involving a local binary database (geoip-lite), a high-performance in-memory cache (lru-cache), and a background worker (eventWorker). By requiring a MaxMind license key during setup, the project ensures that geolocation data remains accurate and up-to-date, enabling real-time global visualization of user traffic.
Sources: README.md:155-165, PROJECT_OUTLINE.md:144-150