GeoLite2/MaxMind GeoIP2 Setup Guide

This guide explains how to configure GeoLite2/MaxMind GeoIP2 Web Service for IP-based geolocation in Lager Guru.

Overview

GeoLite2 integration provides IP-based geolocation services, allowing you to:

• Determine the geographic location of API requests
• Enhance analytics with location data
• Improve AI suggestions with location context

Prerequisites

1. MaxMind Account: Sign up at https://www.maxmind.com/
2. License Key: Obtain your MaxMind License Key from your account dashboard
3. Account ID (optional but recommended): Your MaxMind Account ID

Configuration

Step 1: Get Your Credentials

1. Log in to your MaxMind account
2. Navigate to Services → My License Key
3. Copy your License Key
4. Note your Account ID (usually found in account settings)

Step 2: Set Edge Function Secrets

You need to configure the secrets in your Supabase project. You can do this via:

Option A: Supabase Dashboard

1. Go to your Supabase project dashboard
2. Navigate to Project Settings → Edge Functions → Secrets
3. Add the following secrets:
   • MAXMIND_LICENSE_KEY: Your MaxMind License Key
   • MAXMIND_ACCOUNT_ID: Your MaxMind Account ID (optional but recommended)

Option B: Supabase CLI

# Set the License Key (required)
supabase secrets set MAXMIND_LICENSE_KEY=your_license_key_here

# Set the Account ID (optional but recommended)
supabase secrets set MAXMIND_ACCOUNT_ID=your_account_id_here

Note: You can also use GEOLITE_API_KEY as an alias for MAXMIND_LICENSE_KEY if you prefer.

Step 3: Deploy Edge Functions

Make sure your Edge Functions are deployed:

supabase functions deploy api

Usage

Client-Side Usage

Import and use the geolocation utility in your React components:

import { getLocationFromIP } from "@/lib/geolite";

// Get location for a specific IP address
const location = await getLocationFromIP("8.8.8.8");

if (location) {
  console.log("Country:", location.country);
  console.log("City:", location.city);
  console.log("Coordinates:", location.lat, location.lng);
}

API Endpoint

The geolocation endpoint is available at:

GET /api/geolocation?ip=<ip_address>

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://your-project.supabase.co/functions/v1/api/geolocation?ip=8.8.8.8"

Example Response:

{
  "location": {
    "lat": 37.4056,
    "lng": -122.0775,
    "country": "United States",
    "countryCode": "US",
    "city": "Mountain View",
    "region": "California",
    "postalCode": "94043",
    "timezone": "America/Los_Angeles",
    "accuracy": 5
  },
  "ip": "8.8.8.8"
}

Rate Limiting

The geolocation endpoint includes rate limiting to prevent abuse. The rate limit is applied per IP address.

Troubleshooting

Error: "MaxMind credentials not configured"

• Ensure you've set the MAXMIND_LICENSE_KEY secret in Supabase
• Verify the secret name is correct (case-sensitive)
• Redeploy your Edge Functions after setting secrets

Error: "Failed to fetch geolocation data"

• Check your MaxMind account status and license key validity
• Verify your Account ID is correct (if using GeoIP2 Web Service)
• Check MaxMind API status and your account quota

Error: "Invalid IP address format"

• Ensure the IP address is in valid IPv4 format (e.g., 192.168.1.1)
• IPv6 addresses are not currently supported

API Limits

MaxMind GeoIP2 Web Service has usage limits based on your subscription:

• Free tier: Limited requests per day
• Paid tiers: Higher limits based on your plan

Check your MaxMind account dashboard for current usage and limits.

Security Notes

• Never expose your License Key in client-side code
• Always use Edge Functions to proxy requests to MaxMind API
• The License Key is stored securely in Supabase Edge Function secrets
• Rate limiting is implemented to prevent abuse

Alternative: GeoLite2 MMDB Files

If you prefer to use local GeoLite2 MMDB files instead of the Web Service API:

1. Download GeoLite2 City database from MaxMind
2. Use a library like maxmind to read MMDB files
3. Store the MMDB file in your Edge Function (note: file size limits apply)

This approach doesn't require API calls but requires managing database updates manually.