Repository navigation
feat(web): fill view locations from a GeoIP database when self-hosted - #4158
hjescalona wants to merge 6 commits into
Conversation
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.
|
@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. |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
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.
|
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 ( If it helps, could you add it to the README's list next to GeoLite2 City and DB-IP City Lite? Something like:
Happy to run a few test lookups against your fixtures if you'd like to confirm. |
|
@greptileai review Both findings from the first review are addressed in e4d3731: the README now shows a |
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-regionandx-vercel-ip-cityheaders, 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:
CAP_GEOIP_DATABASE_PATH: path to a GeoIP2/GeoLite2 City.mmdbfile (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, withmmdb-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/trackand the mobile view event: use the database only when the Vercel country header is missing, so Vercel deployments behave exactly as before. The address isgetClientIp(X-Real-IPfirst), the helper the other self-hosted IP checks use. On Railway the lastX-Forwarded-Forhop 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 themaxmindpackage wraps.Without the variable nothing changes. Views recorded before it is set stay without a location, since the event never stored the IP.
Tests:
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).analytics-track-route.test.ts: Vercel's headers still win, and without them the database location is recorded, looked up byX-Real-IPeven whenX-Forwarded-Forends in a different hop.bun run typecheckand Biome pass; themobile-events,mobile-cap-view-notificationandvisitor-countrysuites still pass.I also ran it in production on our Railway instance with DB-IP City Lite (2026-11):
US / Florida / Palm Bay.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.

Confidence 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.
Reviews (2) · Last reviewed commit: "docs(web): explain the Docker Compose se..." · Reviewed by Greptile