Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Enhance proxy guides with critical first-party proxy settings

Bill Yangaeb0982d2436
diff --git a/docs/content/docs/(docs)/proxy-guide/astro.mdx b/docs/content/docs/(docs)/proxy-guide/astro.mdx
index fab0a994f..90080fb6e 100644
--- a/docs/content/docs/(docs)/proxy-guide/astro.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/astro.mdx
@@ -8,6 +8,13 @@ import { Callout } from 'fumadocs-ui/components/callout';
Astro's middleware feature makes it simple to proxy Rybbit tracking. This guide shows how to set up server-side request proxying in your Astro application.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
Astro middleware allows you to intercept and modify requests before they're handled, making it perfect for creating a transparent analytics proxy.
diff --git a/docs/content/docs/(docs)/proxy-guide/caddy.mdx b/docs/content/docs/(docs)/proxy-guide/caddy.mdx
index 399e7632d..9d18ec3ff 100644
--- a/docs/content/docs/(docs)/proxy-guide/caddy.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/caddy.mdx
@@ -9,6 +9,13 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Caddy is a powerful web server with automatic HTTPS that makes reverse proxying simple and secure. This guide shows how to configure Caddy to proxy Rybbit tracking through your own domain.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Combined with automatic HTTPS via Let's Encrypt, Caddy provides a secure, low-configuration solution for proxying analytics.
diff --git a/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx b/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx
index 5c786b0cb..247dd8790 100644
--- a/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx
@@ -9,6 +9,13 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Cloudflare Workers provide a serverless way to proxy Rybbit tracking at the edge, close to your users worldwide. This delivers excellent performance with minimal configuration.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
Cloudflare Workers run on Cloudflare's global network, intercepting and proxying requests before they reach your origin server. This makes them perfect for analytics proxying with built-in caching and ultra-low latency.
diff --git a/docs/content/docs/(docs)/proxy-guide/express.mdx b/docs/content/docs/(docs)/proxy-guide/express.mdx
index e112d825b..72b841b05 100644
--- a/docs/content/docs/(docs)/proxy-guide/express.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/express.mdx
@@ -9,6 +9,13 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Express.js makes it easy to proxy Rybbit tracking using middleware. This guide shows how to set up a reverse proxy using `http-proxy-middleware`.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
The `http-proxy-middleware` package provides a simple way to proxy requests in Express applications, making it perfect for routing analytics requests to Rybbit servers.
diff --git a/docs/content/docs/(docs)/proxy-guide/get-started.mdx b/docs/content/docs/(docs)/proxy-guide/get-started.mdx
index 478e4f934..7c22eebe3 100644
--- a/docs/content/docs/(docs)/proxy-guide/get-started.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/get-started.mdx
@@ -82,10 +82,15 @@ Your domain path β†’ Rybbit backend
**Key requirements:**
- Preserve the HTTP method (GET or POST)
-- Forward necessary headers (User-Agent, X-Forwarded-For, Referer)
+- Forward the browser's original request headers β€” pass through **all** incoming headers except `Host` and hop-by-hop headers (`Connection`, `Content-Length`), rather than hand-picking a few. See [Request Header Forwarding](#request-header-forwarding) for why this matters.
- Maintain request/response body for POST requests
- Set appropriate Content-Type headers
-- For CDN or edge proxies, forward the visitor IP in `X-Forwarded-For` or `X-Real-IP`
+- Forward the visitor IP in `X-Forwarded-For`
+- Enable the **First-Party Proxy** toggle for your site (see below)
+
+### Enable First-Party Proxy in Site Settings
+
+In your Rybbit dashboard, open **Site Settings β†’ Privacy & Security** and enable **First-Party Proxy**. This tells Rybbit that requests for this site arrive via your proxy, so the visitor IP in `X-Forwarded-For` is trusted directly instead of being inferred from network topology. Without it, Rybbit may attribute traffic to your proxy server's IP β€” producing wrong geolocation and merging all visitors into a few users.
### Configure Caching (Optional but Recommended)
@@ -164,22 +169,35 @@ Access-Control-Allow-Headers: Content-Type
## Request Header Forwarding
-For accurate tracking, ensure these headers are forwarded to the Rybbit backend:
+Forward the browser's original headers to the Rybbit backend. The simplest and most robust approach is to pass through **every** incoming request header except `Host` and hop-by-hop headers (`Connection`, `Content-Length` β€” let your HTTP client recompute those).
+
+Why this matters: Rybbit's bot detection scores requests on headers that every real browser sends. A proxy that forwards only `User-Agent` and the visitor IP produces requests that look exactly like a script β€” the events return `200 OK` but are classified as bot traffic and never appear in your dashboard.
+
+If you must whitelist headers instead of passing everything through, this is the minimum set:
| Header | Purpose | Required |
|--------|---------|----------|
| `User-Agent` | Device and browser detection | Yes |
-| `X-Real-IP` or `X-Forwarded-For` | IP address for geolocation | Yes |
+| `X-Forwarded-For` | Visitor IP for geolocation and user identification | Yes |
+| `Accept-Language` | Language detection, bot filtering | Yes |
+| `Accept` | Bot filtering | Yes |
+| `Accept-Encoding` | Bot filtering (must include `gzip`) | Yes |
+| `Sec-Fetch-Site`, `Sec-Fetch-Mode`, `Sec-Fetch-Dest` | Bot filtering (sent by all Chromium browsers) | Yes |
+| `Sec-CH-UA`, `Sec-CH-UA-Mobile`, `Sec-CH-UA-Platform` | Browser detection | Recommended |
| `Referer` | Referrer tracking | Recommended |
-| `Accept-Language` | Language detection | Optional |
+| `Content-Type` | POST body parsing | Yes (POSTs) |
<Callout type="warn">
-**IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the `X-Real-IP` or `X-Forwarded-For` header, all traffic will appear to come from your proxy server's IP.
+**IP Forwarding**: Rybbit uses IP addresses for geolocation (country/city) and creating anonymous user identifiers (hashed IP + User Agent). If you don't forward the visitor IP in `X-Forwarded-For`, all traffic will appear to come from your proxy server's IP.
</Callout>
### Forwarded IP Headers
-If your proxy runs on infrastructure such as Cloudflare Workers, AWS CloudFront, Fastly, or another edge/CDN provider, make sure the proxy sets `X-Forwarded-For` (or `X-Real-IP`) to the original visitor IP. Rybbit reads both **before** the connecting edge IP, so this prevents traffic from being geolocated to the proxy's exit node. `X-Real-IP` takes precedence if both are present, but `X-Forwarded-For` is fully supported and is the right choice on platforms that can't set `X-Real-IP` β€” notably AWS CloudFront, where `X-Real-IP` is on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist).
+Set `X-Forwarded-For` to the original visitor IP before forwarding the request to Rybbit, and enable the **First-Party Proxy** toggle in your site settings so Rybbit trusts it unconditionally.
+
+<Callout type="warn">
+**Use `X-Forwarded-For`, not `X-Real-IP`.** On Rybbit Cloud, `X-Real-IP` is consumed by our edge network (Cloudflare treats it as an internal header) and never reaches the backend β€” a proxy that relies on it will silently fall back to the wrong IP. `X-Forwarded-For` passes through intact. Coincidentally, AWS CloudFront also cannot send `X-Real-IP` (it's on the [origin custom-header denylist](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/add-origin-custom-headers.html#add-origin-custom-headers-denylist)). Setting `X-Real-IP` as well does no harm on self-hosted instances, but never make it the only IP header.
+</Callout>
**Cloudflare Worker example:**
@@ -319,8 +337,9 @@ If something isn't working, check:
1. **Script loads but no events tracked**: Verify all tracking endpoints (`/api/track`, etc.) are proxied
2. **CORS errors**: Ensure CORS headers are preserved from Rybbit backend
3. **404 errors**: Check that URL paths exactly match expected format
-4. **Incorrect geolocation**: Verify `X-Forwarded-For` or `X-Real-IP` is set to the visitor IP
-5. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints
+4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings
+5. **`/track` returns 200 but nothing appears in the dashboard**: Your proxy is probably forwarding too few headers and events are being classified as bot traffic β€” forward the full browser header set (see [Request Header Forwarding](#request-header-forwarding))
+6. **Session replay not working**: Add `/api/replay.js` and `/api/session-replay/record/:siteId` endpoints
For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).
diff --git a/docs/content/docs/(docs)/proxy-guide/laravel.mdx b/docs/content/docs/(docs)/proxy-guide/laravel.mdx
index 2f3075ed5..963b41e56 100644
--- a/docs/content/docs/(docs)/proxy-guide/laravel.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/laravel.mdx
@@ -9,6 +9,13 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Laravel makes it straightforward to proxy Rybbit tracking using routes and the HTTP client. This guide shows how to set up proxy endpoints in your Laravel application.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
Laravel's HTTP client (built on Guzzle) provides an elegant way to proxy requests to Rybbit servers while maintaining full control over headers, caching, and error handling.
diff --git a/docs/content/docs/(docs)/proxy-guide/next-js.mdx b/docs/content/docs/(docs)/proxy-guide/next-js.mdx
index 43a242780..bc4b9012b 100644
--- a/docs/content/docs/(docs)/proxy-guide/next-js.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/next-js.mdx
@@ -9,6 +9,10 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) feature that makes it easy to proxy Rybbit tracking through your own domain. This guide works with both the App Router (Next.js 13+) and Pages Router.
+<Callout type="info">
+Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP β€” the toggle tells Rybbit to trust that forwarded IP directly.
+</Callout>
+
## Overview
Next.js rewrites allow you to map incoming request paths to different destination URLs transparently. This is perfect for proxying analytics since the browser sees requests to your domain while Next.js forwards them to Rybbit's servers behind the scenes.
diff --git a/docs/content/docs/(docs)/proxy-guide/nginx.mdx b/docs/content/docs/(docs)/proxy-guide/nginx.mdx
index 4338e5718..5ec73a70f 100644
--- a/docs/content/docs/(docs)/proxy-guide/nginx.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/nginx.mdx
@@ -9,6 +9,13 @@ import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
Nginx is a powerful web server and reverse proxy that makes it easy to proxy Rybbit tracking through your own domain. This guide shows how to configure Nginx to forward tracking requests to Rybbit servers while caching static scripts for better performance.
+<Callout type="warn">
+**Two settings make or break a first-party proxy:**
+
+1. Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**, so the visitor IP your proxy forwards in `X-Forwarded-For` is trusted directly.
+2. Forward **all** of the browser's request headers, not a hand-picked few. Rybbit's bot detection expects the headers every real browser sends (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” proxies that forward only `User-Agent` get their events accepted with `200 OK` but classified as bot traffic. Use `X-Forwarded-For` for the visitor IP; `X-Real-IP` does not survive Rybbit Cloud's edge.
+</Callout>
+
## Overview
Nginx's `proxy_pass` directive lets you forward requests from your domain to Rybbit's servers. Combined with caching, this provides excellent performance and reliability for proxying analytics.
diff --git a/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx b/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx
index 2d79a3fe1..33e793ca4 100644
--- a/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx
@@ -178,7 +178,7 @@ proxy_pass https://app.rybbit.io;
**Solutions:**
<Callout type="warn">
-**Critical**: The `X-Forwarded-For` (or `X-Real-IP`) header must contain the original client IP for accurate geolocation and user identification. Rybbit reads both before the connecting edge IP. On AWS CloudFront use `X-Forwarded-For` β€” it cannot forward `X-Real-IP`.
+**Critical**: The `X-Forwarded-For` header must contain the original client IP for accurate geolocation and user identification, and the **First-Party Proxy** toggle must be enabled in your site settings. Don't rely on `X-Real-IP` β€” on Rybbit Cloud it never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
</Callout>
**Nginx:**
@@ -209,7 +209,7 @@ onProxyReq: (proxyReq, req) => {
**Cloudflare Workers:**
```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';
-proxyHeaders.set('X-Real-IP', clientIp);
+proxyHeaders.set('X-Forwarded-For', clientIp);
```
---
@@ -218,29 +218,54 @@ proxyHeaders.set('X-Real-IP', clientIp);
**Symptoms:**
- `/analytics/track` returns `200 OK`
-- Events do not appear in the normal analytics dashboard
-- Bot logs or older responses say the event was not tracked because a bot was detected
-- The bot reason mentions `bot asn`
-- Geolocation points to your CDN or proxy region, such as a Cloudflare Worker or AWS CloudFront edge location
+- Events do not appear in the normal analytics dashboard (only under bot traffic)
+- Tracking works fine when the script talks to Rybbit directly, without the proxy
+
+There are two independent causes, and server-side proxies often hit **both**. Work through them in order.
+
+#### Cause 1: Your proxy strips the browser's headers
+
+Rybbit's bot detection scores requests on headers that every real browser sends: `Accept`, `Accept-Language`, `Accept-Encoding` (with `gzip`), and the `Sec-Fetch-*` headers that all Chromium browsers attach. A proxy that forwards only `User-Agent` and the visitor IP produces requests indistinguishable from a script β€” they are accepted with `200 OK` but classified as bots.
-**Cause:** Rybbit is seeing the proxy IP instead of the original visitor IP. This is common when a first-party proxy is hosted on CDN or cloud infrastructure. Those networks use hosting/datacenter ASNs, so traffic can look like bot infrastructure if the visitor IP is not passed in a trusted way.
+**Fix:** forward **all** incoming request headers, minus `Host` and hop-by-hop headers (`Connection`, `Content-Length`). Hand-picking headers is the most common mistake in PHP/WordPress-style proxies.
+
+```php
+// PHP example β€” forward everything except Host/hop-by-hop
+$headers = [];
+foreach (getallheaders() as $name => $value) {
+ if (!in_array(strtolower($name), ['host', 'connection', 'content-length'])) {
+ $headers[] = "$name: $value";
+ }
+}
+$headers[] = 'X-Forwarded-For: ' . $_SERVER['REMOTE_ADDR'];
+```
-Set `X-Forwarded-For` (or `X-Real-IP`) to the original visitor IP before forwarding the request to Rybbit. Rybbit reads both before the connecting edge IP. `X-Real-IP` wins if both are present, but `X-Forwarded-For` is fully supported β€” use it on AWS CloudFront, which cannot forward `X-Real-IP`.
+#### Cause 2: Rybbit sees your proxy's IP instead of the visitor's
+
+First-party proxies typically run on hosting/datacenter infrastructure, so if the visitor IP is not forwarded (or not trusted), traffic carries a datacenter ASN and reinforces bot classification β€” and geolocation points at your proxy's region.
+
+**Fix:**
+
+1. Set `X-Forwarded-For` to the original visitor IP before forwarding to Rybbit.
+2. Enable the **First-Party Proxy** toggle in **Site Settings β†’ Privacy & Security** so Rybbit trusts the forwarded IP unconditionally.
+
+<Callout type="warn">
+Use `X-Forwarded-For`, not `X-Real-IP`. On Rybbit Cloud, `X-Real-IP` never reaches the backend (our edge network consumes it), and AWS CloudFront cannot send it at all.
+</Callout>
**Cloudflare Workers:**
```javascript
const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';
-const proxyHeaders = new Headers(request.headers);
-proxyHeaders.set('X-Real-IP', clientIp);
+const proxyHeaders = new Headers(request.headers); // preserves all browser headers
proxyHeaders.set('X-Forwarded-For', clientIp);
```
**AWS CloudFront:**
-- Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda@Edge (CloudFront cannot forward `X-Real-IP`)
-- Forward `User-Agent`, `Referer`, and `Accept-Language`
+- Set `X-Forwarded-For` to the viewer IP from a CloudFront Function/Lambda@Edge
+- Configure the origin request policy to forward all viewer headers
```javascript
// CloudFront Function (viewer-request)
@@ -615,7 +640,9 @@ When troubleshooting, work through this checklist:
- [ ] Script loads successfully (200 status, correct Content-Type)
- [ ] Tracking endpoint is proxied (`/analytics/track`)
- [ ] POST requests preserve method and body
-- [ ] Client IP is forwarded (`X-Forwarded-For`, `X-Real-IP`)
+- [ ] Client IP is forwarded in `X-Forwarded-For` (not just `X-Real-IP` β€” that header doesn't survive Rybbit Cloud's edge)
+- [ ] **First-Party Proxy** toggle is enabled in Site Settings β†’ Privacy & Security
+- [ ] Full browser header set is forwarded (`Accept`, `Accept-Language`, `Accept-Encoding`, `Sec-Fetch-*`) β€” not just `User-Agent`
- [ ] User-Agent header is preserved
- [ ] CORS headers are preserved (check response headers)
- [ ] Request size limits allow tracking data (1MB minimum)
diff --git a/docs/content/docs/(docs)/proxy-guide/vercel.mdx b/docs/content/docs/(docs)/proxy-guide/vercel.mdx
index 18c04810a..eb2f94064 100644
--- a/docs/content/docs/(docs)/proxy-guide/vercel.mdx
+++ b/docs/content/docs/(docs)/proxy-guide/vercel.mdx
@@ -10,6 +10,10 @@ Vercel makes it easy to proxy Rybbit tracking through their Edge Network. If you
This guide is for static sites or other frameworks deployed on Vercel.
+<Callout type="info">
+Enable **First-Party Proxy** in your Rybbit **Site Settings β†’ Privacy & Security**. Rewrites on this platform automatically forward the browser's headers and set `X-Forwarded-For` to the visitor IP β€” the toggle tells Rybbit to trust that forwarded IP directly.
+</Callout>
+
## Overview
Vercel supports rewrites in `vercel.json`, allowing you to proxy requests through their global Edge Network. This provides excellent performance with automatic caching at edge locations worldwide.