Skip to content

feat(web): fill view locations from a GeoIP database when self-hosted - #4158

Open
hjescalona wants to merge 6 commits into
CapSoftware:mainfrom
Solomedia:feat/self-hosted-geoip
Open

hjescalona wants to merge 6 commits into
CapSoftware:mainfrom
Solomedia:feat/self-hosted-geoip

Conversation

@hjescalona

@hjescalona hjescalona commented Nov 13, 2026 •

Copy link
Copy Markdown

On a self-hosted instance the analytics "Country / City" card always says "Nowhere yet". View locations only come from Vercel's x-vercel-ip-country, x-vercel-ip-country-region and x-vercel-ip-city headers, so any host other than Vercel records every view with an empty country and city. We hit this running Cap on Railway, whose edge sends the client address (X-Real-IP) but no location.

Changes:

  • New optional env var CAP_GEOIP_DATABASE_PATH: path to a GeoIP2/GeoLite2 City .mmdb file (MaxMind GeoLite2 City, DB-IP City Lite, or any file in that format). Documented in the README's Analytics section.
  • apps/web/lib/visitor-location.ts: opens the file once, on the first view that needs it, with mmdb-lib, and maps a record to { country, region, city }. Region is the subdivision code, or its name when the database has no codes (DB-IP Lite). A missing or unreadable file logs one warning and is not retried on every view.
  • /api/analytics/track and the mobile view event: use the database only when the Vercel country header is missing, so Vercel deployments behave exactly as before. The address is getClientIp (X-Real-IP first), the helper the other self-hosted IP checks use. On Railway the last X-Forwarded-For hop is the edge's own address, which put every viewer at the edge POP.
  • mmdb-lib@3.0.3, pinned exactly: MIT, no dependencies, no install scripts. It is the reader that the maxmind package wraps.

Without the variable nothing changes. Views recorded before it is set stay without a location, since the event never stored the IP.

Tests:

  • New visitor-location.test.ts: GeoIP2 and DB-IP record shapes, a record with only a country, missing, private and invalid addresses, and a missing database file (warns once).
  • Two new cases in analytics-track-route.test.ts: Vercel's headers still win, and without them the database location is recorded, looked up by X-Real-IP even when X-Forwarded-For ends in a different hop.
  • bun run typecheck and Biome pass; the mobile-events, mobile-cap-view-notification and visitor-country suites still pass.

I also ran it in production on our Railway instance with DB-IP City Lite (2026-11):

  • A share-page view from an IP in Palm Bay, FL was recorded in Tinybird as US / Florida / Palm Bay.
  • Direct lookups against the same file: 8.8.8.8 → US / California / Mountain View, 2800:3f0:4001::1 → BR / São Paulo / São Paulo, 127.0.0.1 → no location.

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge.

Summary

Adds optional GeoIP lookups for self-hosted viewer analytics while keeping Vercel’s location headers first.

  • Self-hosted view events can include locations from a GeoIP database.

Reviews (2) · Last reviewed commit: "docs(web): explain the Docker Compose se..." · Reviewed by Greptile

Views only get a country and city from Vercel's x-vercel-ip-* headers, so
self-hosted instances record every view with no location and the analytics
map stays empty.

When those headers are missing and CAP_GEOIP_DATABASE_PATH points to a
GeoIP2/GeoLite2 City .mmdb file (MaxMind, DB-IP Lite), look up the client
address instead. Covers the share page tracker and the mobile view event.
Without the variable nothing changes; a missing or unreadable file logs
one warning and views keep no location.
The route test mocks @/lib/rate-limit as a whole, so it now provides
clientAddress, and mocks the GeoIP lookup to check that Vercel's headers
still win and the database fills the location without them.
On Railway the last X-Forwarded-For entry is the edge's own address, so
every self-hosted view was located at the edge POP (Miami for a viewer in
Palm Bay). Use getClientIp, which reads X-Real-IP first, like the other
self-hosted IP checks.
@vercel

vercel Bot commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

@hjescalona is attempting to deploy a commit to the Cap Software Inc Team on Vercel.

A member of the Team first needs to authorize it.

@socket-security

socket-security Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addednpm/​mmdb-lib@​3.0.31001009681100

View full report

Comment thread README.md Resolved
Comment thread apps/web/lib/visitor-location.ts Resolved
The bundled compose file passes cap-web a fixed list of variables, so the
README now shows the override that adds CAP_GEOIP_DATABASE_PATH and mounts
the file. Also drops a comment that only restated geoIpLocation.
@kim-ip2location

Copy link
Copy Markdown

Hi, I'm Kim from IP2Location. Nice approach, keeping the Vercel headers first and falling back to a local file.

Just a note for self-hosters: IP2Location LITE DB11 also comes as an MMDB (DB11LITEMMDB) using the GeoLite2-City compatible schema. lookupLocation() should read it as is (country.iso_code, subdivisions[0], city.names.en), with no code changes. It's free with attribution and updated monthly. After a free sign-up, it can be fetched in a Docker or Railway build step with a download token:

curl -L -o db11.zip "https://www.ip2location.com/download?token=${IP2LOCATION_TOKEN}&file=DB11LITEMMDB"

If it helps, could you add it to the README's list next to GeoLite2 City and DB-IP City Lite? Something like:

CAP_GEOIP_DATABASE_PATH: path to a City .mmdb file, such as MaxMind GeoLite2 City, DB-IP City Lite, or IP2Location LITE DB11.

Happy to run a few test lookups against your fixtures if you'd like to confirm.

@hjescalona

Copy link
Copy Markdown
Author

@greptileai review

Both findings from the first review are addressed in e4d3731: the README now shows a docker-compose.override.yml that mounts the database into cap-web, and the doc comment is removed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants