GeoLite2 and the CARTO key

GeoMetrikks needs two free keys. MaxMind's key lets it download the GeoLite2 databases that turn an IP address into a place and a network. CARTO's key goes with every basemap tile the map loads.

MaxMind GeoLite2Copy Anchor Link

Sign up at maxmind.com/en/geolite2/signup, then generate a license key in your account. Put your account ID and the key in .env:

MAXMINDDB_USER_ID=<your-account-id>
MAXMINDDB_LICENSE_KEY=<your-license-key>

Then run docker compose up -d. Compose recreates the app container with the new values, and the app downloads the databases at startup.

Using the databases means accepting the GeoLite2 EULA.

What gets downloadedCopy Anchor Link

Two databases, both with the same key:

• GeoLite2 City places each request on the map and feeds the country and city filters and the geo analytics.
• GeoLite2 ASN adds the network (AS number and organization) behind each request, for Top ASNs and the ASN filters. Set GEOIP_ASN_ENABLED=false to skip it. It defaults to true. Without the ASN database the app still ingests traffic, just without network data.

The files live in /app/data/geoip inside the container. The compose file keeps that folder on the geoip_data volume, so a recreated container keeps its databases. With keys set, you don't need to handle the .mmdb files yourself.

RefreshCopy Anchor Link

At startup the app downloads a database that is missing or older than GEOIP_REFRESH_DAYS (default 7). A scheduled job then downloads fresh copies every GEOIP_REFRESH_DAYS days. Settings > Scheduler lists it as "Refresh GeoLite2 databases from MaxMind", and its Run now button fetches new copies straight away. When the files change, ingestion switches to the new ones without a restart.

Without keys, the app keeps whatever database file it already has and warns in the log once it is older than GEOIP_REFRESH_DAYS. The EULA requires a refresh within 30 days.

Place-name languageCopy Anchor Link

GEOIP_LOCALES sets the language of country and city names, as a JSON list. The default is ["en"]. The allowed values are the languages GeoLite2 carries: de, en, es, fr, ja, pt-BR, ru and zh-CN. Startup fails on any other value, with an error that lists the allowed ones. For German names:

GEOIP_LOCALES=["de"]

With more than one entry, each name comes from the first language in the list that has one.

Geo-degraded modeCopy Anchor Link

If the app has no usable GeoLite2 City database, it starts in geo-degraded mode. The UI and the API work and show the data already stored, but ingestion does not start, so no new traffic is recorded. A banner at the top of the UI says which settings to add.

Ingestion starts by itself once a database file appears. This happens the next time the GeoLite2 refresh job runs, either on its schedule or from Run now on Settings > Scheduler. The job also picks up a file you place in /app/data/geoip yourself, on its next scheduled run or when you click Run now. If the keys were missing, add them and run docker compose up -d, which downloads the database at startup.

CARTO basemap keyCopy Anchor Link

The map draws its basemap from CARTO, with OpenStreetMap data. CARTO's terms want one API key per deployment, so every GeoMetrikks install needs its own. Keys are free; request one at carto.com/basemaps/apikey and set it in .env:

MAP_CARTO_API_KEY=<your-key>

Then run docker compose up -d.

The reader's browser sends the key with every basemap request, so anyone who opens the map can see it. Treat it as public. Without a key the map loads today, but CARTO may watermark or refuse keyless tiles at any time.

The map shows the CARTO and OpenStreetMap attribution in its corner. Both licenses require it, so keep it visible.

Esri satellite keyCopy Anchor Link

The map's Satellite view is optional. It draws Esri World Imagery, and Esri needs its own key. Create a free ArcGIS Location Platform account at location.arcgis.com, make an API key with basemap access, and set it in .env:

MAP_ESRI_API_KEY=<your-key>

Then run docker compose up -d.

Like the CARTO key, the browser sends it with every satellite tile, so treat it as public. Without a key the Satellite switch is greyed out. Esri counts tile use against the account's monthly free allowance.

With Satellite on, Esri's credit joins CARTO's. On a phone it folds behind an Esri button at the end of the credit line, and a tap opens it.

The other GeoIP and map settings are in the configuration reference under GeoIP and Map.