How to enrich rtcstats-server with GeoIP data

Add country and city data to your WebRTC sessions using MaxMind's free GeoLite2 database.

rtcstats-server can annotate every session with country and city based on the client's IP address. When a user in Tokyo reports bad quality, you see "Tokyo, Japan" in the session metadata instead of a raw IP. When your TURN servers in Frankfurt are overloaded, you can spot it because German sessions show relay connections while French sessions don't.

What is important to understand here is that:

We keep coarse granularity for geolocation. This is to maintain user privacy
Geolocation takes place before anonymizing IP addresses, a process that takes place by default

All it takes is a MaxMind GeoLite2 database loaded locally on your rtcstats-server instance.

How it works

When rtcstats-server receives data from rtcstats-js, it scans for IP addresses as part of the anonymization pass. Right before anonymization strips the IPs, the server looks each one up in the GeoLite2 database and writes the country and city into the session metadata.

The lookup is local - no network calls, no external API latency. The database file sits on the same machine as rtcstats-server.

Step 1: get a MaxMind account

Create a free account at MaxMind GeoLite2 and generate a license key. The GeoLite2 database is free for most use cases.

You need two credentials:

Account ID (a number)
License key (a string)

Step 2: download the GeoLite2-City database

Pull the database during your deployment or build step. The exact mechanism depends on your hosting, but the core command is the same:

wget \
  --user=$MAXMIND_ACCOUNT_ID \
  --password=$MAXMIND_LICENSE_KEY \
  https://download.maxmind.com/geoip/databases/GeoLite2-City/download?suffix=tar.gz \
  -O GeoLite-City.mmdb.tgz &&
tar -xzf GeoLite-City.mmdb.tgz &&
mv GeoLite2-City*/GeoLite2-City.mmdb .

This downloads the tarball, extracts it, and places GeoLite2-City.mmdb in the current directory.

Docker deployments: Add this to your Dockerfile or an init script that runs at container build time. Once the .mmdb file is baked into the image, the running container never needs the MaxMind credentials. Smaller attack surface, cleaner runtime.

DigitalOcean Apps Platform: Paste the command into the Build Command field and set MAXMIND_ACCOUNT_ID and MAXMIND_LICENSE_KEY as build-time environment variables. The file lands at /workspace/GeoLite2-City.mmdb. See the full DigitalOcean deployment guide for details.

Step 3: configure rtcstats-server

Point rtcstats-server at the database file. In your config YAML:

maxmind:
    path: GeoLite2-City.mmdb

Or via the NODE_CONFIG environment variable:

{"maxmind":{"path":"GeoLite2-City.mmdb"}}

Adjust the path to wherever you placed the file. On DigitalOcean Apps Platform, that's /workspace/GeoLite2-City.mmdb. In a Docker container, it's wherever your Dockerfile copies it.

Step 4: verify it works

Start rtcstats-server, make a WebRTC call, and let the session complete. Then query your database:

SELECT
  server.created_at,
  server.blob_url,
  server.id,
  features_metadata.location_city,
  features_metadata.location_country,
  features_metadata.location_continent
FROM "rtcstats-server" AS server
JOIN features_metadata ON features_metadata.dump_id = server.id
ORDER BY server.created_at DESC;

You should see country, city, and continent populated for each session.

Keeping the database fresh

Geolocation databases change as IP blocks get reassigned. We recommend downloading a fresh copy of the GeoLite2 database on every deployment of rtcstats-server. If your deploy pipeline runs the download command above, you're already doing this automatically.