πΈ Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.
docs: fix ingestion, proxy, script, and self-hosting docs (#1340)
Goldflag10195321010f
diff --git a/.env.example b/.env.exampleindex d4ce88766..5160c539c 100644--- a/.env.example+++ b/.env.example@@ -1,26 +1,31 @@# Domain and URL Configuration-DOMAIN_NAME=demo.rybbit.com+# Replace with the domain or subdomain that points to this server+DOMAIN_NAME=your.domain.comBASE_URL="https://${DOMAIN_NAME}"# Authentication and Security-BETTER_AUTH_SECRET=insecure-secret+# Required. Generate a random secret with: openssl rand -hex 32+BETTER_AUTH_SECRET=replace-with-output-of-openssl-rand-hex-32DISABLE_SIGNUP=false# Webserver Configuration# Set to false to disable the built-in Caddy webserverUSE_WEBSERVER=true# Host port mappings - these control how services are exposed-# Format: "host_binding:container_port" or "port:container_port"-HOST_BACKEND_PORT=127.0.0.1:3001-HOST_CLIENT_PORT=127.0.0.1:3002+# Format: "host_ip:host_port:container_port" or "host_port:container_port"+# Without a host_ip the port is published on all interfaces.+HOST_BACKEND_PORT=127.0.0.1:3001:3001+HOST_CLIENT_PORT=127.0.0.1:3002:3002CLICKHOUSE_DB=analytics-CLICKHOUSE_USER=default+# The backend always connects to ClickHouse as the "default" user, so don't set CLICKHOUSE_USER.CLICKHOUSE_PASSWORD=frogPOSTGRES_DB=analyticsPOSTGRES_USER=frogPOSTGRES_PASSWORD=frog+REDIS_PASSWORD=changeme+# External Service Tokens (optional)MAPBOX_TOKEN=diff --git a/CONTRIBUTE.md b/CONTRIBUTE.mdindex 2502af014..e5d045a0b 100644--- a/CONTRIBUTE.md+++ b/CONTRIBUTE.md@@ -53,8 +53,41 @@ pnpm install --frozen-lockfilepnpm dev```-Configure the backend environment and its Postgres, ClickHouse, and Redis services-before starting the app. The client runs on port 3002 and the backend on port 3001.+Before starting the app, run the databases and point both apps at them:++1. Start only Postgres, ClickHouse, and Redis from the root `docker-compose.yml`.+ They listen on localhost with the compose defaults (Postgres user and password+ `frog`, ClickHouse password `frog`, Redis password `changeme`):++ ```bash+ docker compose up -d postgres clickhouse redis+ ```++2. Copy `server/.env.example` to `server/.env` and set these values to match+ the compose defaults:++ ```bash+ CLICKHOUSE_PASSWORD=frog+ POSTGRES_USER=frog+ POSTGRES_PASSWORD=frog+ REDIS_PASSWORD=changeme+ BETTER_AUTH_SECRET=<output of openssl rand -hex 32>+ ```++3. Create `client/.env.local` with the backend URL:++ ```bash+ NEXT_PUBLIC_BACKEND_URL=http://localhost:3001+ ```++4. Create the Postgres tables (the Docker image does this on start; local dev+ does not):++ ```bash+ pnpm --filter rybbit-backend db:migrate+ ```++The client runs on port 3002 and the backend on port 3001.`pnpm dev` builds shared code first, then starts its TypeScript watcher alongsideboth apps. The backend's existing dev command compiles once; restart it afterbackend changes.@@ -70,7 +103,7 @@ Run these commands from the repository root:| `pnpm build:server` | Build shared code and the backend, including the tracker || `pnpm test` | Build shared code and run both test suites once || `pnpm typecheck` | Build shared code and type-check both apps |-| `pnpm lint` | Run the client's ESLint command |+| `pnpm lint` | Run the client's ESLint command (currently a no-op, since `client/eslint.config.mjs` is commented out; use `pnpm typecheck`) |The root test command runs one package at a time with four workers to bound thememory used by the backend's in-memory Postgres tests.diff --git a/docs/README.md b/docs/README.mdindex 018d73730..5897e9cb7 100644--- a/docs/README.md+++ b/docs/README.md@@ -13,20 +13,20 @@ pnpm devyarn dev```-Open http://localhost:3000 with your browser to see the result.+Open http://localhost:3003 with your browser to see the result.## ExploreIn the project, you can see:-- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.-- `app/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.+- `src/lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.+- `src/app/[locale]/layout.config.tsx`: Shared options for layouts, optional but preferred to keep.| Route | Description || ------------------------- | ------------------------------------------------------ |-| `app/(home)` | The route group for your landing page and other pages. |-| `app/docs` | The documentation layout and pages. |-| `app/api/search/route.ts` | The Route Handler for search. |+| `src/app/[locale]/(home)` | The route group for your landing page and other pages. |+| `src/app/[locale]/docs` | The documentation layout and pages. |+| `src/app/api/search/route.ts` | The Route Handler for search. |### Fumadocs MDXdiff --git a/docs/content/docs/(docs)/localhost-tracking.mdx b/docs/content/docs/(docs)/localhost-tracking.mdxindex 65dfc3a27..42414882e 100644--- a/docs/content/docs/(docs)/localhost-tracking.mdx+++ b/docs/content/docs/(docs)/localhost-tracking.mdx@@ -5,16 +5,14 @@ description: How Rybbit handles traffic from localhost during developmentimport { Callout } from 'fumadocs-ui/components/callout';-Rybbit does not restrict tracking to your registered domain β the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet has a valid `data-site-id`, events sent during local development are recorded like any other traffic.+Rybbit does not restrict tracking to your registered domain β the tracking script works from `localhost` (or any other origin) out of the box. As long as your snippet carries a valid site ID, events sent during local development are recorded like any other traffic.```html-<script- defer- src="https://app.rybbit.io/api/script.js"- data-site-id="YOUR_SITE_ID">-</script>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>```+Older snippets that pass the ID as `data-site-id` still work.+<Callout type="warning">Because localhost traffic is tracked by default, the usual problem is the opposite one: development visits polluting your production analytics. Use one of the approaches below to keep your data clean.</Callout>@@ -36,8 +34,7 @@ export function Analytics() {return (<scriptdefer- src="https://app.rybbit.io/api/script.js"- data-site-id={siteId}+ src={`https://app.rybbit.io/api/script.js?siteId=${siteId}`}/>);}@@ -55,8 +52,7 @@ export function Analytics() {return (<scriptdefer- src="https://app.rybbit.io/api/script.js"- data-site-id={process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}+ src={`https://app.rybbit.io/api/script.js?siteId=${process.env.NEXT_PUBLIC_RYBBIT_SITE_ID}`}/>);}@@ -67,8 +63,7 @@ export function Analytics() {if (process.env.NODE_ENV === 'production') {const script = document.createElement('script');script.defer = true;- script.src = 'https://app.rybbit.io/api/script.js';- script.setAttribute('data-site-id', 'YOUR_SITE_ID');+ script.src = 'https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID';document.head.appendChild(script);}```@@ -81,7 +76,8 @@ If you want the script loaded everywhere but excluded from your stats, use your**Events not showing up from localhost?**-- Confirm `data-site-id` matches the site you're looking at in the dashboard+- Confirm the `siteId` in the script URL (or `data-site-id`) matches the site you're looking at in the dashboard- Check the browser console for errors and the Network tab for `POST` requests to `/api/track`- Disable ad blockers or privacy extensions β they commonly block analytics scripts on any origin, including localhost-- Make sure the page isn't excluded by your site's IP, path, or user-agent exclusion rules+- Make sure the page isn't excluded by your site's IP, hostname, path, or user-agent exclusion rules+- Headless or automated browsers (Puppeteer, Playwright, Selenium) are classified as bots, so test in a normal browserdiff --git a/docs/content/docs/(docs)/managing-your-installation.mdx b/docs/content/docs/(docs)/managing-your-installation.mdxindex ec10a9002..eff3bd823 100644--- a/docs/content/docs/(docs)/managing-your-installation.mdx+++ b/docs/content/docs/(docs)/managing-your-installation.mdx@@ -13,13 +13,36 @@ You probably need to run `chmod +x *.sh` before running the scripts.### Updating Your Installation-Rybbit is updated frequently with new features and bug fixes. You can update your installation by running the following commands:+Rybbit is updated frequently with new features and bug fixes. To update, run:-**update.sh**: Update to the latest version by pulling new code and rebuilding containers- ```bash- git pull- ./update.sh- ```+```bash+./update.sh+```++The script runs `git stash` and `git pull` to update the repository, pulls the latest Docker images, and recreates the containers.++<Callout type="warn">+`update.sh` stashes any local changes to tracked files, such as edits to `Caddyfile` or `docker-compose.yml`, and does not restore them. Your `.env` file is not affected. To get stashed edits back, run `git stash list` and `git stash pop`. Keep your customizations in `.env` and in a `docker-compose.override.yml` file, which Docker Compose loads automatically and `git stash` leaves alone.+</Callout>++### Image tags++The backend and client images are published to `ghcr.io/rybbit-io/rybbit-backend` and `ghcr.io/rybbit-io/rybbit-client` with these tags:++| Tag | Points to |+| --- | --- |+| `latest` | The most recent release (the default) |+| `vX.Y.Z` | A specific release, e.g. `v2.9.2` |+| `edge` | The latest commit on `master`, which may not be released yet |+| `sha-<short commit>` | A single commit |++`docker compose pull` fetches whatever `IMAGE_TAG` points to. To pin a release, set it in `.env`:++```bash+IMAGE_TAG=v2.9.2+```++Then run `./update.sh` or `docker compose pull` followed by your usual start command. Remove the line to go back to `latest`.### Restarting Your Installation@@ -76,14 +99,16 @@ You can access the databases by running the following commands:```### Edit Session Replay Retention Policy-The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following command:+The default session replay retention policy is 30 days. This may be too long for some users as session replays can take up a lot of space. You can edit it by running the following commands:```bashdocker exec -it clickhouse clickhouse-client --database analyticsALTER TABLE session_replay_events MODIFY TTL toDateTime(timestamp) + INTERVAL 14 DAY;-ALTER TABLE session_replay_metadata MODIFY TTL start_time + INTERVAL 14 DAY;+ALTER TABLE session_replay_metadata_v2 MODIFY TTL toDateTime(start_time) + INTERVAL 14 DAY;```+The older `session_replay_metadata` table is no longer written to, so its 30-day TTL empties it on its own.+## Anonymous Usage TelemetryTo help us improve Rybbit, self-hosted instances automatically send anonymous usage statistics to our cloud service. This includes:diff --git a/docs/content/docs/(docs)/mcp/index.mdx b/docs/content/docs/(docs)/mcp/index.mdxindex 461e753f8..37d567af3 100644--- a/docs/content/docs/(docs)/mcp/index.mdx+++ b/docs/content/docs/(docs)/mcp/index.mdx@@ -21,6 +21,8 @@ If your client supports the MCP authorization flow β Claude Code, Codex, Claud2. Create a key in the **Personal API Keys** section.3. Copy it immediately. Rybbit only shows a new key once.+A personal key acts as you. If the connection should belong to the organization and keep working when people leave, an admin or owner can instead create an **organization API key** under **Settings β Organization**. It reaches every site in that organization with admin authority. See [API keys](/docs/api/getting-started#generating-api-keys) for both kinds.+A key created without permissions can do everything its user can do. To hand an agent a narrower credential, create the key with scoped permissions (`POST /api/user/api-keys` with a `permissions` object, e.g. `{"analytics": ["read"], "goals": ["read", "write"]}`): the MCP tool list and every API call are then limited to those `resource:action` scopes. `write` implies `read` on the same resource, and scopes never elevate β org admin/owner requirements still apply. Deleting the key revokes the connection.### 2. Add the endpoint@@ -231,7 +233,8 @@ OAuth clients request scopes through the standard grant. Rybbit advertises the s## Troubleshooting- **401 Unauthorized:** The client did not send a Bearer credential, or the key/token is invalid, expired, or revoked. OAuth-capable clients re-authenticate automatically via the `WWW-Authenticate` challenge.-- **OAuth login loop or "table does not exist" (self-hosted):** Run `npm run db:push` in `server/` to create the OAuth tables, then retry.+- **OAuth login loop or "table does not exist" (self-hosted):** The backend container applies database migrations each time it starts. Check `docker compose logs backend` for a failed migration, fix the cause, and recreate the backend with `docker compose up -d backend`. `docker compose restart` keeps the old environment, so it doesn't pick up changes to `.env`.+- **OAuth discovery fails (self-hosted):** Your reverse proxy must send `/.well-known/oauth-*` and `/.well-known/openid-configuration*` to the backend, as the built-in Caddy config does. See [Configure your reverse proxy](/docs/self-hosting-guides/self-hosting-manual#configure-your-reverse-proxy).- **403 in tool results:** The key's user lacks access to that site or organization, or holds too low a role for the tool (`"Insufficient role"` names the role required). Check the `role` field in `list_sites`.- **403 "Insufficient scope":** The credential was created without the `resource:action` scope this tool needs (the `required` field names it). Use a key or OAuth grant that includes it.- **429 Too Many Requests:** The API key exceeded its plan's rate limit.diff --git a/docs/content/docs/(docs)/proxy-guide/astro.mdx b/docs/content/docs/(docs)/proxy-guide/astro.mdxindex 90080fb6e..73b46ee44 100644--- a/docs/content/docs/(docs)/proxy-guide/astro.mdx+++ b/docs/content/docs/(docs)/proxy-guide/astro.mdx@@ -27,23 +27,23 @@ Astro middleware allows you to intercept and modify requests before they're hand## Prerequisites-- Astro 2.0 or later (with SSR or hybrid rendering enabled)+- Astro 5 or later, with a server adapter (examples below use `@astrojs/node`)- Your Rybbit instance URL:- **Cloud hosted**: `https://app.rybbit.io`- **Self-hosted**: Your instance URL- Your Rybbit site ID<Callout type="warn">-This guide requires SSR (Server-Side Rendering) or hybrid mode. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.+This guide requires on-demand (server) rendering with an adapter. Static sites cannot proxy requests server-side. For static sites on platforms like Vercel or Netlify, use their platform-specific proxy configurations.</Callout>## Implementation<Steps>-### Enable SSR in Astro+### Enable Server Rendering in Astro-Update `astro.config.mjs` to enable SSR:+Update `astro.config.mjs` to render on demand:```javascript// astro.config.mjs@@ -51,13 +51,15 @@ import { defineConfig } from 'astro/config';import node from '@astrojs/node';export default defineConfig({- output: 'server', // or 'hybrid'+ output: 'server',adapter: node({mode: 'standalone',}),});```+Astro 5 removed `output: 'hybrid'`. Use `output: 'server'` so the middleware runs on every request, including `/analytics/*` paths that have no page of their own.+Install the Node adapter if not already installed:```bash@@ -80,50 +82,50 @@ Create `src/middleware.ts` (or `.js` for JavaScript):```typescript// src/middleware.ts-import type { MiddlewareHandler } from 'astro';+import { defineMiddleware } from 'astro:middleware';const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';-export const onRequest: MiddlewareHandler = async (context, next) => {- const { request } = context;- const url = new URL(request.url);+// Proxies every /analytics/* route (script.js, replay.js, track, identify,+// site/tracking-config/:siteId, site/:siteId/feature-flags/evaluate,+// session-replay/record/:siteId) to Rybbit's /api/*.+export const onRequest = defineMiddleware(async (context, next) => {+ const url = new URL(context.request.url);- // Check if this is an analytics requestif (url.pathname.startsWith('/analytics/')) {- return proxyToRybbit(request, url.pathname);+ // clientAddress is the visitor IP as your adapter reports it+ return proxyToRybbit(context.request, url, context.clientAddress);}- // Continue with normal request handlingreturn next();-};+});-async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {+async function proxyToRybbit(request: Request, url: URL, clientIp: string): Promise<Response> {try {- // Map paths: /analytics/* β /api/*- let rybbitPath = pathname.replace('/analytics/', '/api/');-- const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;-- // Get client IP from headers- const forwardedFor = request.headers.get('x-forwarded-for');- const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';+ // Map paths: /analytics/* β /api/*, keeping the query string+ const rybbitUrl = `${RYBBIT_HOST}${url.pathname.replace('/analytics/', '/api/')}${url.search}`;- // Forward request+ // Forward the browser's headers and set the visitor IPconst proxyHeaders = new Headers(request.headers);- proxyHeaders.set('X-Real-IP', clientIp);+ proxyHeaders.delete('host');proxyHeaders.set('X-Forwarded-For', clientIp);+ const hasBody = request.method !== 'GET' && request.method !== 'HEAD';const response = await fetch(rybbitUrl, {method: request.method,headers: proxyHeaders,- body: request.method !== 'GET' ? await request.text() : undefined,+ body: hasBody ? await request.text() : undefined,});- // Return proxied response+ // fetch() already decoded the body, so drop the upstream encoding headers+ const headers = new Headers(response.headers);+ headers.delete('content-encoding');+ headers.delete('content-length');+return new Response(response.body, {status: response.status,statusText: response.statusText,- headers: response.headers,+ headers,});} catch (error) {console.error('Rybbit proxy error:', error);@@ -132,53 +134,13 @@ async function proxyToRybbit(request: Request, pathname: string): Promise<Respon}```-For JavaScript projects:--```javascript-// src/middleware.js-const RYBBIT_HOST = import.meta.env.RYBBIT_HOST || 'https://app.rybbit.io';--export const onRequest = async (context, next) => {- const { request } = context;- const url = new URL(request.url);-- if (url.pathname.startsWith('/analytics/')) {- return proxyToRybbit(request, url.pathname);- }-- return next();-};--async function proxyToRybbit(request, pathname) {- try {- // Map paths: /analytics/* β /api/*- let rybbitPath = pathname.replace('/analytics/', '/api/');-- const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;- const forwardedFor = request.headers.get('x-forwarded-for');- const clientIp = forwardedFor ? forwardedFor.split(',')[0].trim() : '127.0.0.1';-- const proxyHeaders = new Headers(request.headers);- proxyHeaders.set('X-Real-IP', clientIp);- proxyHeaders.set('X-Forwarded-For', clientIp);+For JavaScript projects, use the same code in `src/middleware.js` without the type annotations.- const response = await fetch(rybbitUrl, {- method: request.method,- headers: proxyHeaders,- body: request.method !== 'GET' ? await request.text() : undefined,- });+<Callout type="warn">+Don't fall back to a fixed address such as `127.0.0.1` when you can't find the visitor IP. With **First-Party Proxy** enabled, Rybbit trusts the `X-Forwarded-For` you send, so a constant fallback makes every visitor share one IP: one location and visitors merged together. `context.clientAddress` comes from your adapter; if your Astro server sits behind another reverse proxy, configure the adapter or that proxy so `clientAddress` is the visitor's address, not the proxy's.+</Callout>- return new Response(response.body, {- status: response.status,- statusText: response.statusText,- headers: response.headers,- });- } catch (error) {- console.error('Rybbit proxy error:', error);- return new Response('Analytics proxy error', { status: 500 });- }-}-```+If the feature flag route isn't proxied, `rybbit.flag()` silently returns your fallback; the `/analytics/` prefix match above already covers it. Web vitals collection is bundled into `script.js`; `replay.js` is only loaded when session replay is enabled for the site.### Update Your Layout@@ -198,7 +160,7 @@ const { title } = Astro.props;<title>{title}</title><!-- Rybbit Analytics -->- <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+ <script is:inline src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><slot />@@ -206,6 +168,10 @@ const { title } = Astro.props;</html>```+`is:inline` stops Astro from bundling the tag, so it stays a plain external script. Older snippets that pass the ID as `data-site-id` still work.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.+### Start Development Server```bash@@ -226,7 +192,7 @@ Astro middleware intercepts requests before they're processed:1. Request to `/analytics/script.js` enters middleware2. Middleware proxies to `https://app.rybbit.io/api/script.js`-3. Client IP headers are preserved+3. The visitor IP from `context.clientAddress` is sent in `X-Forwarded-For`4. Response is returned to browser## Advanced Configuration@@ -240,7 +206,8 @@ Add caching for scripts:const cache = new Map<string, { response: Response; timestamp: number }>();const CACHE_TTL = 3600000; // 1 hour in milliseconds-async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {+async function proxyToRybbit(request: Request, url: URL, clientIp: string): Promise<Response> {+ const pathname = url.pathname;// Cache GET requests for scriptsif (request.method === 'GET' && pathname.endsWith('.js')) {const cached = cache.get(pathname);@@ -269,17 +236,16 @@ async function proxyToRybbit(request: Request, pathname: string): Promise<ResponOnly proxy in production:```typescript-export const onRequest: MiddlewareHandler = async (context, next) => {- const { request } = context;- const url = new URL(request.url);+export const onRequest = defineMiddleware(async (context, next) => {+ const url = new URL(context.request.url);// Only proxy in productionif (import.meta.env.PROD && url.pathname.startsWith('/analytics/')) {- return proxyToRybbit(request, url.pathname);+ return proxyToRybbit(context.request, url, context.clientAddress);}return next();-};+});```### Error Logging@@ -287,13 +253,13 @@ export const onRequest: MiddlewareHandler = async (context, next) => {Add detailed error logging:```typescript-async function proxyToRybbit(request: Request, pathname: string): Promise<Response> {+async function proxyToRybbit(request: Request, url: URL, clientIp: string): Promise<Response> {try {// ... proxy logic} catch (error) {const errorDetails = {message: error instanceof Error ? error.message : 'Unknown error',- pathname,+ pathname: url.pathname,method: request.method,timestamp: new Date().toISOString(),};@@ -316,7 +282,7 @@ async function proxyToRybbit(request: Request, pathname: string): Promise<Respon**Problem**: Requests bypass middleware.**Solution**:-1. Ensure SSR or hybrid mode is enabled in `astro.config.mjs`+1. Ensure `output: 'server'` and an adapter are set in `astro.config.mjs`2. Verify middleware file is in `src/middleware.ts` (not in subdirectory)3. Check adapter is installed: `npm install @astrojs/node`@@ -358,7 +324,7 @@ npm install @astrojs/vercel```javascript// astro.config.mjsimport { defineConfig } from 'astro/config';-import vercel from '@astrojs/vercel/serverless';+import vercel from '@astrojs/vercel';export default defineConfig({output: 'server',@@ -377,7 +343,7 @@ npm install @astrojs/netlify```javascript// astro.config.mjsimport { defineConfig } from 'astro/config';-import netlify from '@astrojs/netlify/functions';+import netlify from '@astrojs/netlify';export default defineConfig({output: 'server',diff --git a/docs/content/docs/(docs)/proxy-guide/caddy.mdx b/docs/content/docs/(docs)/proxy-guide/caddy.mdxindex 5785117fd..5cc8dbab9 100644--- a/docs/content/docs/(docs)/proxy-guide/caddy.mdx+++ b/docs/content/docs/(docs)/proxy-guide/caddy.mdx@@ -28,7 +28,7 @@ Caddy's `reverse_proxy` directive makes it incredibly easy to proxy requests. Co## Prerequisites-- Caddy installed (version 2.0 or later)+- Caddy installed (version 2.7 or later, for the `{client_ip}` placeholder)- Domain pointing to your server- Your Rybbit instance URL:- **Cloud hosted**: `https://app.rybbit.io`@@ -62,8 +62,8 @@ yourdomain.com {handle /analytics/script.js {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}header_up X-Forwarded-Proto {scheme}}rewrite * /api/script.js@@ -73,28 +73,18 @@ yourdomain.com {handle /analytics/replay.js {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/replay.js}- # Web Vitals metrics script- handle /analytics/metrics.js {- reverse_proxy https://app.rybbit.io {- header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}- }- rewrite * /api/metrics.js- }-# Event tracking endpointhandle /analytics/track {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}header_up Content-Type {header.Content-Type}}rewrite * /api/track@@ -104,8 +94,8 @@ yourdomain.com {handle /analytics/identify {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}header_up Content-Type {header.Content-Type}}rewrite * /api/identify@@ -115,8 +105,8 @@ yourdomain.com {handle /analytics/session-replay/record/* {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}header_up Content-Type {header.Content-Type}}uri replace /analytics/session-replay/record /api/session-replay/record@@ -126,11 +116,22 @@ yourdomain.com {handle /analytics/site/tracking-config/* {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}uri replace /analytics/site/tracking-config /api/site/tracking-config}++ # Feature flag evaluation+ handle /analytics/site/*/feature-flags/evaluate {+ reverse_proxy https://app.rybbit.io {+ header_up Host app.rybbit.io+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}+ header_up Content-Type {header.Content-Type}+ }+ uri replace /analytics/site/ /api/site/+ }}```@@ -138,6 +139,21 @@ yourdomain.com {Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.</Callout>+Web vitals collection is bundled into `script.js`; `replay.js` is only loaded when session replay is enabled for the site. If the feature flag route isn't proxied, `rybbit.flag()` silently returns your fallback.++<Callout type="warn">+`{client_ip}` is the address that connected to Caddy. If a CDN such as Cloudflare sits in front of Caddy, that address is the CDN's edge server, so Rybbit would place every visitor at the edge's location. List the CDN's IP ranges in the `trusted_proxies` global option at the top of your Caddyfile, so `{client_ip}` becomes the visitor's IP:++```txt+{+ servers {+ # Your CDN's published IP ranges, e.g. https://www.cloudflare.com/ips/+ trusted_proxies static 198.51.100.0/24 2001:db8::/32+ }+}+```+</Callout>+</Tab><Tab>@@ -149,8 +165,8 @@ yourdomain.com {handle /analytics/script.js {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/script.js}@@ -159,14 +175,21 @@ yourdomain.com {handle /analytics/track {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/track}}```+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults:++- Pageviews, SPA navigation, query strings and outbound links are tracked.+- Web vitals, error tracking, session replay, button clicks, copy and form tracking stay off.+- Feature flags return their fallback.+- `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user.+</Tab><Tab>@@ -179,15 +202,15 @@ yourdomain.com {handle_path /analytics/* {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api{uri}}}```-This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`.+This proxies all `/analytics/*` requests to `https://app.rybbit.io/api/*`, so every tracking route (including feature flags and `/identify`) is covered.</Tab></Tabs>@@ -232,7 +255,7 @@ Update your HTML to load the script from your proxied domain:<html><head><!-- ... other head elements -->- <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+ <script src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><!-- Your content -->@@ -240,7 +263,9 @@ Update your HTML to load the script from your proxied domain:</html>```-Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.+Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard. Older snippets that pass the ID as `data-site-id` still work.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.### Verify the Setup@@ -289,8 +314,8 @@ yourdomain.com {handle /analytics/script.js {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/script.jsheader Cache-Control "public, max-age=3600"@@ -300,8 +325,8 @@ yourdomain.com {handle /analytics/site/tracking-config/* {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}uri replace /analytics/site/tracking-config /api/site/tracking-configheader Cache-Control "public, max-age=300"@@ -311,8 +336,8 @@ yourdomain.com {handle /analytics/track {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/trackheader Cache-Control "no-store"@@ -330,8 +355,8 @@ Use a dedicated subdomain for analytics:analytics.yourdomain.com {reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api{uri}}@@ -339,7 +364,7 @@ analytics.yourdomain.com {Then use:```html-<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>+<script src="https://analytics.yourdomain.com/script.js?siteId=123" defer></script>```### Request Size Limits@@ -355,8 +380,8 @@ yourdomain.com {}reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}uri replace /analytics/session-replay/record /api/session-replay/record}@@ -374,8 +399,8 @@ Use Caddy's environment variable support:handle_path /analytics/* {reverse_proxy {$RYBBIT_HOST:https://app.rybbit.io} {header_up Host {upstream_hostport}- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api{uri}}@@ -398,15 +423,15 @@ yourdomain.com {handle /analytics/track {rate_limit {zone analytics {- key {remote_host}+ key {client_ip}events 100window 1m}}reverse_proxy https://app.rybbit.io {header_up Host app.rybbit.io- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}rewrite * /api/track}@@ -434,14 +459,16 @@ The `rate_limit` directive requires the [caddy-ratelimit plugin](https://github.**Problem**: All visitors show same location.**Solution**:-Ensure you're forwarding client IP:+Ensure you're forwarding client IP, and that **First-Party Proxy** is on in your site settings:```txtreverse_proxy https://app.rybbit.io {- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}```+If a CDN sits in front of Caddy, also add its IP ranges to `trusted_proxies` (see the note under **Full Proxy**). Otherwise every visitor gets the CDN edge's location.+### 502 Bad Gateway**Problem**: Caddy returns 502 when accessing analytics endpoints.diff --git a/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx b/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdxindex 247dd8790..df15d44a7 100644--- a/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx+++ b/docs/content/docs/(docs)/proxy-guide/cloudflare-workers.mdx@@ -49,7 +49,7 @@ Log in to Cloudflare Dashboard and create a new Worker:### Update Worker Code-Replace the default code with the proxy implementation:+Replace the default code with the proxy implementation. The examples use the ES module syntax (`export default { fetch }`), which current Workers use; environment variables and secrets arrive as the `env` argument of `fetch`.<Tabs items={['Full Proxy (Recommended)', 'Minimal Proxy', 'With Environment Variables']}><Tab>@@ -57,28 +57,30 @@ Replace the default code with the proxy implementation:```javascript// Cloudflare Worker for Rybbit Analytics Proxy-const RYBBIT_HOST = 'https://app.rybbit.io';+// Proxies every /analytics/* route (script.js, replay.js, track, identify,+// site/tracking-config/:siteId, site/:siteId/feature-flags/evaluate,+// session-replay/record/:siteId) to Rybbit's /api/*.-addEventListener('fetch', event => {- event.respondWith(handleRequest(event.request));-});+const RYBBIT_HOST = 'https://app.rybbit.io';-async function handleRequest(request) {- const url = new URL(request.url);+export default {+ async fetch(request, env, ctx) {+ const url = new URL(request.url);- // Only proxy /analytics/* paths- if (!url.pathname.startsWith('/analytics/')) {- // Pass through to origin- return fetch(request);- }+ // Only proxy /analytics/* paths+ if (!url.pathname.startsWith('/analytics/')) {+ // Pass through to origin+ return fetch(request);+ }- try {- return await proxyToRybbit(request, url);- } catch (error) {- console.error('Proxy error:', error);- return new Response('Analytics proxy error', { status: 500 });- }-}+ try {+ return await proxyToRybbit(request, url);+ } catch (error) {+ console.error('Proxy error:', error);+ return new Response('Analytics proxy error', { status: 500 });+ }+ },+};async function proxyToRybbit(request, url) {// Map paths: /analytics/* β /api/*@@ -157,78 +159,83 @@ async function proxyToRybbit(request, url) {const RYBBIT_HOST = 'https://app.rybbit.io';-addEventListener('fetch', event => {- event.respondWith(handleRequest(event.request));-});+export default {+ async fetch(request) {+ const url = new URL(request.url);-async function handleRequest(request) {- const url = new URL(request.url);+ // Only proxy /analytics/script.js and /analytics/track+ if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {+ const rybbitPath = url.pathname.replace('/analytics/', '/api/');+ const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}${url.search}`;- // Only proxy /analytics/script.js and /analytics/track- if (url.pathname === '/analytics/script.js' || url.pathname === '/analytics/track') {- const rybbitPath = url.pathname.replace('/analytics/', '/api/');- const rybbitUrl = `${RYBBIT_HOST}${rybbitPath}`;+ const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';- const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';+ const proxyHeaders = new Headers(request.headers);+ proxyHeaders.set('X-Real-IP', clientIp);+ proxyHeaders.set('X-Forwarded-For', clientIp);- const proxyHeaders = new Headers(request.headers);- proxyHeaders.set('X-Real-IP', clientIp);- proxyHeaders.set('X-Forwarded-For', clientIp);-- return fetch(rybbitUrl, {- method: request.method,- headers: proxyHeaders,- body: request.method === 'POST' ? request.body : undefined,- });- }+ return fetch(rybbitUrl, {+ method: request.method,+ headers: proxyHeaders,+ body: request.method === 'POST' ? request.body : undefined,+ });+ }- // Pass through to origin- return fetch(request);-}+ // Pass through to origin+ return fetch(request);+ },+};```+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults:++- Pageviews, SPA navigation, query strings and outbound links are tracked.+- Web vitals, error tracking, session replay, button clicks, copy and form tracking stay off.+- Feature flags return their fallback.+- `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user.+</Tab><Tab>Using Workers secrets for configuration:```javascript-addEventListener('fetch', event => {- event.respondWith(handleRequest(event.request, event.env));-});+export default {+ async fetch(request, env) {+ const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';+ const url = new URL(request.url);-async function handleRequest(request, env) {- const RYBBIT_HOST = env.RYBBIT_HOST || 'https://app.rybbit.io';- const url = new URL(request.url);-- if (!url.pathname.startsWith('/analytics/')) {- return fetch(request);- }+ if (!url.pathname.startsWith('/analytics/')) {+ return fetch(request);+ }- // Map paths: /analytics/* β /api/*- let rybbitPath = url.pathname.replace('/analytics/', '/api/');+ // Map paths: /analytics/* β /api/*+ const rybbitUrl = new URL(url.pathname.replace('/analytics/', '/api/'), RYBBIT_HOST);+ rybbitUrl.search = url.search; // Preserve query params (e.g. ?siteId=)- const rybbitUrl = new URL(rybbitPath, RYBBIT_HOST);- const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';+ const clientIp = request.headers.get('CF-Connecting-IP') || '0.0.0.0';- const proxyHeaders = new Headers(request.headers);- proxyHeaders.set('X-Real-IP', clientIp);- proxyHeaders.set('X-Forwarded-For', clientIp);+ const proxyHeaders = new Headers(request.headers);+ proxyHeaders.set('X-Real-IP', clientIp);+ proxyHeaders.set('X-Forwarded-For', clientIp);- return fetch(rybbitUrl.toString(), {- method: request.method,- headers: proxyHeaders,- body: request.method !== 'GET' ? request.body : undefined,- });-}+ return fetch(rybbitUrl.toString(), {+ method: request.method,+ headers: proxyHeaders,+ body: request.method !== 'GET' && request.method !== 'HEAD' ? request.body : undefined,+ });+ },+};```Set environment variable in Cloudflare Dashboard:-**Workers & Pages** β Your Worker β **Settings** β **Variables** β Add `RYBBIT_HOST`+**Workers & Pages** β Your Worker β **Settings** β **Variables and Secrets** β Add `RYBBIT_HOST`. With Wrangler, set it under `vars` in your Wrangler config instead.</Tab></Tabs>+The full and environment-variable versions forward every `/analytics/*` path, so feature flag evaluation (`/analytics/site/:siteId/feature-flags/evaluate`) and `/identify` are covered. If you narrow the paths, keep the feature flag route: without it, `rybbit.flag()` silently returns your fallback. Web vitals collection is bundled into `script.js`; `replay.js` is only loaded when session replay is enabled for the site.+### Deploy WorkerClick **Save and Deploy** to publish your worker.@@ -253,9 +260,13 @@ The route pattern `yourdomain.com/analytics/*` ensures the worker only runs forAdd the script to your website:```html-<script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script>```+Older snippets that pass the ID as `data-site-id` still work.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.+### Verify the Setup1. **Visit your site** with Developer Tools open@@ -339,30 +350,40 @@ async function checkRateLimit(ip) {### Logging and Analytics-Log proxy usage:+Log proxy usage by wrapping `proxyToRybbit` and calling the wrapper from `fetch`:```javascript-async function handleRequest(request) {+async function proxyWithLogging(request, url) {const startTime = Date.now();+ const response = await proxyToRybbit(request, url);- try {- const response = await proxyToRybbit(request, url);- const duration = Date.now() - startTime;-- // Log to Cloudflare Analytics Engine (if enabled)- console.log({- path: url.pathname,- status: response.status,- duration,- cached: response.headers.get('X-Cache-Status') === 'HIT',- });+ // Shows up in Workers Logs / `wrangler tail`+ console.log({+ path: url.pathname,+ status: response.status,+ duration: Date.now() - startTime,+ cached: response.headers.get('X-Cache-Status') === 'HIT',+ });- return response;- } catch (error) {- console.error('Proxy error:', error);- return new Response('Error', { status: 500 });- }+ return response;}++export default {+ async fetch(request, env, ctx) {+ const url = new URL(request.url);++ if (!url.pathname.startsWith('/analytics/')) {+ return fetch(request);+ }++ try {+ return await proxyWithLogging(request, url);+ } catch (error) {+ console.error('Proxy error:', error);+ return new Response('Analytics proxy error', { status: 500 });+ }+ },+};```## Cost Considerations@@ -411,9 +432,11 @@ Most sites stay within the free tier. Bandwidth is unlimited on all Cloudflare pUse `CF-Connecting-IP` header:```javascriptconst clientIp = request.headers.get('CF-Connecting-IP');-proxyHeaders.set('X-Real-IP', clientIp);+proxyHeaders.set('X-Forwarded-For', clientIp);```+Also enable **First-Party Proxy** in your site settings so Rybbit trusts that header.+### Deployment errors**Problem**: Worker fails to deploy.diff --git a/docs/content/docs/(docs)/proxy-guide/express.mdx b/docs/content/docs/(docs)/proxy-guide/express.mdxindex 72b841b05..8dd50e9a6 100644--- a/docs/content/docs/(docs)/proxy-guide/express.mdx+++ b/docs/content/docs/(docs)/proxy-guide/express.mdx@@ -69,6 +69,8 @@ Install `dotenv` if not already: `npm install dotenv`### Add Proxy Middleware to Express+These examples use `http-proxy-middleware` v3. Version 3 removed the `onProxyReq`/`onError` options (use `on: { proxyReq, error }`) and `logLevel` (use `logger`).+<Tabs items={['Full Proxy (Recommended)', 'Minimal Proxy', 'TypeScript']}><Tab>@@ -83,36 +85,27 @@ const { createProxyMiddleware } = require('http-proxy-middleware');const app = express();const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';-// Rybbit Analytics Proxy-// Proxy all /analytics/* requests to Rybbit+// Rybbit Analytics Proxy. Register it before express.json() or any other body parser.+// Express strips the '/analytics' mount path, so a request for /analytics/script.js+// reaches the proxy as /script.js and goes to RYBBIT_HOST/api/script.js.+// This covers every tracking route: script.js, replay.js, track, identify,+// site/tracking-config/:siteId, site/:siteId/feature-flags/evaluate and+// session-replay/record/:siteId.app.use('/analytics', createProxyMiddleware({- target: RYBBIT_HOST,+ target: `${RYBBIT_HOST}/api`,changeOrigin: true,- pathRewrite: {- '^/analytics': '/api', // Rewrite /analytics/script.js to /api/script.js- },- onProxyReq: (proxyReq, req, res) => {- // Forward client IP for accurate geolocation- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('X-Real-IP', clientIp);+ on: {+ proxyReq: (proxyReq, req) => {+ // Forward the visitor IP for geolocation and visitor identification+ const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;+ proxyReq.setHeader('X-Forwarded-For', clientIp);+ },},- logLevel: 'warn',+ logger: console,}));-// Exception for site config endpoint (different path structure)-app.use('/analytics/site/tracking-config', createProxyMiddleware({- target: RYBBIT_HOST,- changeOrigin: true,- pathRewrite: {- '^/analytics/site': '/api/site', // Rewrite to /api/site/tracking-config- },- onProxyReq: (proxyReq, req, res) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('X-Real-IP', clientIp);- },-}));+// Body parsers go after the proxy+app.use(express.json());// Your other routesapp.get('/', (req, res) => {@@ -125,6 +118,8 @@ app.listen(PORT, () => {});```+`http-proxy-middleware` forwards the browser's request headers as they are, which is what Rybbit's bot detection expects.+</Tab><Tab>@@ -139,17 +134,20 @@ const { createProxyMiddleware } = require('http-proxy-middleware');const app = express();const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';-// Proxy script and track endpoints only-app.use(['/analytics/script.js', '/analytics/track'], createProxyMiddleware({+// Proxy script and track endpoints only. Mounted without a path, so+// pathFilter sees the full URL and pathRewrite can match '^/analytics'.+app.use(createProxyMiddleware({target: RYBBIT_HOST,changeOrigin: true,+ pathFilter: ['/analytics/script.js', '/analytics/track'],pathRewrite: {'^/analytics': '/api',},- onProxyReq: (proxyReq, req, res) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('X-Real-IP', clientIp);+ on: {+ proxyReq: (proxyReq, req) => {+ const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;+ proxyReq.setHeader('X-Forwarded-For', clientIp);+ },},}));@@ -159,6 +157,13 @@ app.listen(PORT, () => {});```+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults:++- Pageviews, SPA navigation, query strings and outbound links are tracked.+- Web vitals, error tracking, session replay, button clicks, copy and form tracking stay off.+- Feature flags return their fallback.+- `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user.+</Tab><Tab>@@ -167,37 +172,27 @@ For TypeScript projects:```typescript// server.tsimport 'dotenv/config';-import express, { Request, Response } from 'express';-import { createProxyMiddleware, Options } from 'http-proxy-middleware';+import express from 'express';+import { createProxyMiddleware } from 'http-proxy-middleware';const app = express();const RYBBIT_HOST = process.env.RYBBIT_HOST || 'https://app.rybbit.io';-const proxyOptions: Options = {- target: RYBBIT_HOST,- changeOrigin: true,- pathRewrite: {- '^/analytics': '/api',- },- onProxyReq: (proxyReq, req, res) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp as string);- proxyReq.setHeader('X-Real-IP', clientIp as string);- },- logLevel: 'warn',-};--app.use('/analytics', createProxyMiddleware(proxyOptions));--app.use('/analytics/site/tracking-config', createProxyMiddleware({- target: RYBBIT_HOST,+// Before any body parser; '/analytics' is stripped, so target ends in /api+app.use('/analytics', createProxyMiddleware<express.Request, express.Response>({+ target: `${RYBBIT_HOST}/api`,changeOrigin: true,- pathRewrite: {- '^/analytics/site': '/api/site',+ on: {+ proxyReq: (proxyReq, req) => {+ const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress || '';+ proxyReq.setHeader('X-Forwarded-For', clientIp);+ },},- onProxyReq: proxyOptions.onProxyReq,+ logger: console,}));+app.use(express.json());+const PORT = process.env.PORT || 3000;app.listen(PORT, () => {console.log(`Server running on port ${PORT}`);@@ -207,14 +202,24 @@ app.listen(PORT, () => {</Tab></Tabs>+<Callout type="warn">+Register the proxy **before** `express.json()`, `express.urlencoded()` or any other body parser. A body parser that runs first reads the request stream, and the proxy then forwards `/track`, `/identify` and session replay POSTs with an empty body. If a parser has to run first, import `fixRequestBody` from `http-proxy-middleware` and call `fixRequestBody(proxyReq, req)` at the end of your `proxyReq` handler so it writes the parsed body back out.+</Callout>++If the feature flag route (`/analytics/site/:siteId/feature-flags/evaluate`) isn't proxied, `rybbit.flag()` silently returns your fallback. Web vitals collection is bundled into `script.js`; `replay.js` is only loaded when session replay is enabled for the site.+### Update Your Tracking ScriptIn your HTML or template files:```html-<script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script>```+Older snippets that pass the ID as `data-site-id` still work.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.+### Start Your Server```bash@@ -246,68 +251,20 @@ npx nodemon server.jsThe `http-proxy-middleware` intercepts requests matching the specified paths and forwards them to Rybbit:1. Request to `/analytics/script.js` is intercepted-2. Path is rewritten to `/api/script.js`-3. Request is forwarded to `https://app.rybbit.io/api/script.js`-4. Client IP headers are added for accurate tracking+2. Express strips the `/analytics` mount path, so the proxy sees `/script.js`+3. The proxy appends that to the target and forwards to `https://app.rybbit.io/api/script.js`+4. The visitor IP is set in `X-Forwarded-For`5. Response is sent back to the browser## Advanced Configuration### Caching Responses-Add caching for better performance:--```javascript-const NodeCache = require('node-cache');-const cache = new NodeCache({ stdTTL: 3600 }); // 1 hour default--// Install: npm install node-cache--// Caching middleware for scripts-const cacheMiddleware = (req, res, next) => {- const key = req.originalUrl;- const cachedResponse = cache.get(key);-- if (cachedResponse) {- res.set('X-Cache-Status', 'HIT');- return res.send(cachedResponse);- }-- // Store original send- const originalSend = res.send.bind(res);- res.send = (body) => {- cache.set(key, body);- res.set('X-Cache-Status', 'MISS');- return originalSend(body);- };- next();-};--// Apply caching only to script files-app.use('/analytics/script.js', cacheMiddleware);-app.use('/analytics/script.js', createProxyMiddleware({- // ... proxy config-}));-```+Rybbit already sends `Cache-Control` headers on its scripts (`script.js` for 1 hour, `replay.js` for 1 day), and the proxy passes them through. If you want edge caching, put a CDN in front of your app rather than caching inside Express: the proxy streams responses, so middleware that wraps `res.send` never sees them.### Request Size Limits-For session replay uploads, increase body size limit:--```javascript-const express = require('express');-const app = express();--// Increase limit for session replay endpoints-app.use('/analytics/session-replay', express.json({ limit: '10mb' }));-app.use('/analytics/session-replay', createProxyMiddleware({- target: RYBBIT_HOST,- changeOrigin: true,- pathRewrite: {- '^/analytics': '/api',- },-}));-```+The proxy streams request bodies to Rybbit without parsing them, so Express body-size limits don't apply to proxied routes. Don't add `express.json()` to `/analytics` routes to raise a limit: it consumes the body and the proxy forwards an empty request.### Rate Limiting@@ -339,19 +296,18 @@ Add error handling for proxy failures:```javascriptapp.use('/analytics', createProxyMiddleware({- target: RYBBIT_HOST,+ target: `${RYBBIT_HOST}/api`,changeOrigin: true,- pathRewrite: {- '^/analytics': '/api',- },- onError: (err, req, res) => {- console.error('Proxy error:', err);- res.status(500).json({ error: 'Analytics proxy error' });- },- onProxyReq: (proxyReq, req, res) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('X-Real-IP', clientIp);+ on: {+ proxyReq: (proxyReq, req) => {+ const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;+ proxyReq.setHeader('X-Forwarded-For', clientIp);+ },+ error: (err, req, res) => {+ console.error('Proxy error:', err);+ res.statusCode = 502;+ res.end('Analytics proxy error');+ },},}));```@@ -385,13 +341,10 @@ app.use('/analytics', createProxyMiddleware({Increase timeout limits:```javascriptapp.use('/analytics', createProxyMiddleware({- target: RYBBIT_HOST,+ target: `${RYBBIT_HOST}/api`,changeOrigin: true,timeout: 30000, // 30 secondsproxyTimeout: 30000,- pathRewrite: {- '^/analytics': '/api',- },}));```@@ -402,32 +355,42 @@ app.use('/analytics', createProxyMiddleware({**Solution**:Ensure IP forwarding is configured:```javascript-onProxyReq: (proxyReq, req, res) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('X-Real-IP', clientIp);-}+on: {+ proxyReq: (proxyReq, req) => {+ const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;+ proxyReq.setHeader('X-Forwarded-For', clientIp);+ },+},```+Also enable **First-Party Proxy** in your site settings so Rybbit trusts that header.+### Path rewriting issues**Problem**: 404 errors on Rybbit endpoints.**Solution**:-Check path rewriting is correct:+When you mount the proxy with `app.use('/analytics', ...)`, Express strips `/analytics` before the proxy sees the URL, so a `pathRewrite` of `'^/analytics'` never matches. Either put `/api` in the target:```javascript-pathRewrite: {- '^/analytics': '/api', // /analytics/script.js β /api/script.js-}+app.use('/analytics', createProxyMiddleware({ target: `${RYBBIT_HOST}/api`, changeOrigin: true }));```+or mount without a path and use `pathFilter` with `pathRewrite: { '^/analytics': '/api' }`.Debug by logging:```javascript-onProxyReq: (proxyReq, req, res) => {- console.log('Proxying:', req.method, req.path, 'β', proxyReq.path);-}+on: {+ proxyReq: (proxyReq, req) => {+ console.log('Proxying:', req.method, req.originalUrl, 'β', proxyReq.path);+ },+},```+### Tracking or replay requests arrive empty++**Problem**: `/track` returns 400, or session replay never records.++**Solution**: A body parser (`express.json()`, `body-parser`) ran before the proxy and consumed the request body. Register the proxy first, or use `fixRequestBody` (see above).+## Related Resources- [Tracking Script Documentation](/docs/script) - Script configurationdiff --git a/docs/content/docs/(docs)/proxy-guide/get-started.mdx b/docs/content/docs/(docs)/proxy-guide/get-started.mdxindex 6e29a84cf..15745dde8 100644--- a/docs/content/docs/(docs)/proxy-guide/get-started.mdx+++ b/docs/content/docs/(docs)/proxy-guide/get-started.mdx@@ -35,7 +35,12 @@ Rybbit uses several endpoints for tracking. You can choose between a minimal set| `/api/script.js` | GET | Main tracking script | 1 hour || `/api/track` | POST | Event tracking endpoint | No cache |-This minimal setup enables basic pageview and event tracking, but won't support session replay or some advanced features.+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults:++- Pageviews, SPA navigation, query strings and outbound links are tracked.+- Web vitals, error tracking, session replay, button clicks, copy and form tracking stay off.+- Feature flags return their fallback.+- `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user.</Tab><Tab>@@ -46,19 +51,19 @@ This minimal setup enables basic pageview and event tracking, but won't support|----------|--------|---------|-------|| `/api/script.js` | GET | Main tracking script (minified) | 1 hour || `/api/replay.js` | GET | Session replay recording script | 1 day |-| `/api/metrics.js` | GET | Web Vitals metrics script | 1 day || `/api/track` | POST | Event tracking endpoint | No cache || `/api/identify` | POST | User identification endpoint | No cache || `/api/session-replay/record/:siteId` | POST | Session replay data upload | No cache || `/api/site/tracking-config/:siteId` | GET | Site configuration | 5 minutes |+| `/api/site/:siteId/feature-flags/evaluate` | POST | Feature flag evaluation | No cache |-This setup supports all Rybbit features including session replay, Web Vitals, and custom events.+This setup supports every tracking feature, including your Tracking tab settings, session replay, web vitals, user identification and feature flags. If the feature flag route isn't proxied, `rybbit.flag()` silently returns your fallback.</Tab></Tabs><Callout type="info">-The session replay and metrics scripts (`/api/replay.js` and `/api/metrics.js`) are loaded dynamically by the main script when those features are enabled in your site settings. You don't need to include them in your HTML.+Web vitals collection is bundled into `script.js`. The only script loaded on demand is `/api/replay.js`, which the main script fetches when session replay is enabled for the site. You don't need to include it in your HTML.</Callout>## Implementation Steps@@ -80,6 +85,8 @@ Your domain path β Rybbit backend... and so on```+Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.+**Key requirements:**- Preserve the HTTP method (GET or POST)- 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.@@ -117,14 +124,16 @@ Change your script tag to load from your proxied domain instead of directly from**Before (direct loading):**```html-<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>```**After (proxied):**```html-<script src="https://yourdomain.com/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="https://yourdomain.com/analytics/script.js?siteId=YOUR_SITE_ID" defer></script>```+Older snippets that pass the ID as `data-site-id` still work.+<Callout type="info">**How Auto-Discovery Works**: The Rybbit script automatically extracts the analytics host from its own `src` attribute by splitting on `/script.js`. This means when it loads from `https://yourdomain.com/analytics/script.js`, it automatically sends all tracking data to `https://yourdomain.com/analytics/*` endpoints.</Callout>@@ -158,12 +167,7 @@ X-Frame-Options: DENYReferrer-Policy: strict-origin-when-cross-origin```-**CORS headers** (should be preserved from Rybbit):-```-Access-Control-Allow-Origin: *-Access-Control-Allow-Methods: GET, POST, OPTIONS-Access-Control-Allow-Headers: Content-Type-```+**CORS headers**: pass Rybbit's CORS response headers through unchanged rather than setting your own. On the tracking endpoints Rybbit echoes the requesting page's origin back in `Access-Control-Allow-Origin` (not `*`) and answers preflight `OPTIONS` requests itself. If your proxy serves the script from the same origin as your pages, the browser never needs CORS for it.</Steps>@@ -183,8 +187,7 @@ If you must whitelist headers instead of passing everything through, this is the| `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 |+| `Referer` | Session replay metadata (event referrers come from the request body) | Recommended || `Content-Type` | POST body parsing | Yes (POSTs) |<Callout type="warn">@@ -340,6 +343,8 @@ If something isn't working, check:4. **Incorrect geolocation**: Verify `X-Forwarded-For` is set to the visitor IP and the **First-Party Proxy** toggle is enabled in site settings5. **`/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+7. **Tracking tab settings ignored, or `identify()` does nothing**: Proxy `/api/site/tracking-config/:siteId` and `/api/identify`+8. **`rybbit.flag()` always returns the fallback**: Proxy `/api/site/:siteId/feature-flags/evaluate`For more detailed troubleshooting, see our [troubleshooting guide](/docs/proxy-guide/troubleshooting).diff --git a/docs/content/docs/(docs)/proxy-guide/index.mdx b/docs/content/docs/(docs)/proxy-guide/index.mdxindex a61a62fbd..0ec96a5a3 100644--- a/docs/content/docs/(docs)/proxy-guide/index.mdx+++ b/docs/content/docs/(docs)/proxy-guide/index.mdx@@ -22,7 +22,7 @@ Proxying Rybbit's tracking script through your own domain helps bypass ad blockeWhen you add Rybbit's tracking script directly to your website using the default installation:```html-<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>```The browser loads the script from `app.rybbit.io`, which ad blockers can identify and block as third-party analytics. Even though Rybbit is privacy-focused and doesn't use cookies, some ad blockers use aggressive blocking rules that target any analytics domains.@@ -50,7 +50,7 @@ Proxying doesn't compromise user privacy:- No cookies are used (Rybbit remains cookieless)- User data is still processed according to your privacy policy- GDPR, CCPA, and other privacy regulations remain fully satisfied-- Users can still opt out through browser settings or Do Not Track+- Visitors who opt out stay opted out: the script does nothing when `window.__RYBBIT_OPTOUT__` is set or `localStorage` holds a `disable-rybbit` key (`disable-<namespace>` if you set `data-namespace`; see [Hiding your own traffic](/docs/hiding-own-traffic)). The script checks for these when it loads, so a change takes effect on the next page load. Rybbit does not read Do Not Track or Global Privacy Control signals.### Better Performance (Optional)@@ -66,8 +66,9 @@ Here's the flow when you proxy Rybbit:1. **User visits your website**: Your HTML includes the tracking script from your domain```html- <script src="https://yourdomain.com/analytics/script.js" data-site-id="123"></script>+ <script src="https://yourdomain.com/analytics/script.js?siteId=123" defer></script>```+ Older snippets that pass the ID as `data-site-id` still work.2. **Script loads from your domain**: Your server proxies the request to Rybbit's servers- Request: `yourdomain.com/analytics/script.js` β proxied to β `app.rybbit.io/api/script.js`@@ -78,11 +79,14 @@ Here's the flow when you proxy Rybbit:const analyticsHost = src.split("/script.js")[0];// Result: "https://yourdomain.com/analytics"```+ Because of this, keep the proxied file named `script.js`. A renamed file (for example `/analytics/a.js`) sends every request to the wrong place.4. **Tracking data sent through your domain**: All analytics events are sent to your domain and proxied to Rybbit- Event tracking: `yourdomain.com/analytics/track` β proxied to β `app.rybbit.io/api/track`+ - User identification: `yourdomain.com/analytics/identify` β proxied- Session replay: `yourdomain.com/analytics/session-replay/record/{siteId}` β proxied- Configuration: `yourdomain.com/analytics/site/tracking-config/{siteId}` β proxied+ - Feature flags: `yourdomain.com/analytics/site/{siteId}/feature-flags/evaluate` β proxied. If this route is missing, `rybbit.flag()` silently returns your fallback.5. **Data appears in your Rybbit dashboard**: No changes needed in the Rybbit interfacediff --git a/docs/content/docs/(docs)/proxy-guide/laravel.mdx b/docs/content/docs/(docs)/proxy-guide/laravel.mdxindex 963b41e56..98221bebc 100644--- a/docs/content/docs/(docs)/proxy-guide/laravel.mdx+++ b/docs/content/docs/(docs)/proxy-guide/laravel.mdx@@ -65,103 +65,108 @@ Then implement the proxy logic:namespace App\Http\Controllers;use Illuminate\Http\Request;-use Illuminate\Support\Facades\Http;use Illuminate\Support\Facades\Cache;+use Illuminate\Support\Facades\Http;+use Illuminate\Support\Facades\Log;class AnalyticsProxyController extends Controller{+ // Headers that describe the hop to your app, not the visitor's browser,+ // plus credentials (e.g. HTTP basic auth on a staging site) Rybbit must not get.+ private const SKIP_HEADERS = [+ 'host', 'content-length', 'connection', 'cookie', 'keep-alive',+ 'transfer-encoding', 'upgrade', 'x-forwarded-for', 'x-forwarded-host',+ 'x-forwarded-proto', 'x-forwarded-port', 'x-real-ip',+ 'authorization', 'proxy-authorization',+ ];+private string $rybbitHost;public function __construct(){- $this->rybbitHost = config('services.rybbit.host', 'https://app.rybbit.io');+ $this->rybbitHost = rtrim(config('services.rybbit.host', 'https://app.rybbit.io'), '/');}/**- * Proxy script requests (GET)+ * Scripts (GET), cached for 1 hour*/public function proxyScript(Request $request, string $script){- // Cache scripts for 1 hour- $cacheKey = "rybbit_script_{$script}";-- return Cache::remember($cacheKey, 3600, function () use ($script, $request) {- return $this->forwardRequest("api/{$script}", 'GET', $request);- });+ return $this->cached("rybbit_script_{$script}", 3600, "api/{$script}", $request);}/**- * Proxy tracking requests (POST)+ * Site tracking config (GET), cached for 5 minutes*/- public function proxyTrack(Request $request)+ public function proxySiteConfig(Request $request, string $siteId){- return $this->forwardRequest('api/track', 'POST', $request);+ return $this->cached("rybbit_config_{$siteId}", 300, "api/site/tracking-config/{$siteId}", $request);}/**- * Proxy identify requests (POST)+ * Every POST endpoint: track, identify, feature flags, session replay*/- public function proxyIdentify(Request $request)+ public function proxyPost(Request $request){- return $this->forwardRequest('api/identify', 'POST', $request);- }+ // Strip the leading "analytics/" and forward to the same path under /api+ $path = 'api/' . substr($request->path(), strlen('analytics/'));- /**- * Proxy session replay recording (POST)- */- public function proxySessionReplay(Request $request, string $siteId)- {- return $this->forwardRequest("api/session-replay/record/{$siteId}", 'POST', $request);+ return $this->forward('POST', $path, $request);}- /**- * Proxy site configuration (GET)- */- public function proxySiteConfig(Request $request, string $siteId)+ private function cached(string $key, int $ttl, string $path, Request $request){- // Cache config for 5 minutes- $cacheKey = "rybbit_config_{$siteId}";+ $cached = Cache::get($key);++ if ($cached === null) {+ $response = $this->forward('GET', $path, $request);++ if ($response->getStatusCode() !== 200) {+ return $response;+ }- return Cache::remember($cacheKey, 300, function () use ($siteId, $request) {- return $this->forwardRequest("api/site/tracking-config/{$siteId}", 'GET', $request);- });+ $cached = [+ 'body' => $response->getContent(),+ 'type' => $response->headers->get('Content-Type'),+ ];+ Cache::put($key, $cached, $ttl);+ }++ return response($cached['body'], 200)->header('Content-Type', $cached['type']);}- /**- * Forward request to Rybbit backend- */- private function forwardRequest(string $path, string $method, Request $request)+ private function forward(string $method, string $path, Request $request){$url = "{$this->rybbitHost}/{$path}";- // Get client IP- $clientIp = $request->header('X-Forwarded-For', $request->ip());+ // Pass the browser's headers through; Rybbit's bot detection expects them.+ $headers = collect($request->headers->all())+ ->reject(fn ($value, $name) => in_array(strtolower($name), self::SKIP_HEADERS, true))+ ->map(fn ($values) => implode(', ', $values))+ ->all();- // Build HTTP request- $httpRequest = Http::timeout(30)- ->withHeaders([- 'X-Real-IP' => $clientIp,- 'X-Forwarded-For' => $clientIp,- 'User-Agent' => $request->header('User-Agent'),- 'Referer' => $request->header('Referer', ''),- ]);+ // The visitor IP. $request->ip() honors your TrustProxies settings.+ $headers['X-Forwarded-For'] = $request->ip();+ // Replace the copied Accept-Encoding (the keys above are lowercase) with+ // gzip, which the HTTP client can decode. Send it only if the browser+ // offered gzip: bot detection flags clients that don't.+ $headers['accept-encoding'] = str_contains($request->header('Accept-Encoding', ''), 'gzip') ? 'gzip' : 'identity';++ $http = Http::timeout(30)->withHeaders($headers);try {- if ($method === 'POST') {- $response = $httpRequest->post($url, $request->all());- } else {- $response = $httpRequest->get($url);- }+ $response = $method === 'POST'+ // Forward the raw body. $request->all() would pass through+ // ConvertEmptyStringsToNull, and Rybbit rejects null fields.+ ? $http->withBody($request->getContent(), $request->header('Content-Type', 'application/json'))->post($url)+ : $http->get($url);return response($response->body(), $response->status())- ->header('Content-Type', $response->header('Content-Type'));- } catch (\Exception $e) {- \Log::error('Rybbit proxy error', [- 'url' => $url,- 'error' => $e->getMessage(),- ]);-- return response()->json(['error' => 'Analytics proxy error'], 500);+ ->header('Content-Type', $response->header('Content-Type') ?: 'text/plain');+ } catch (\Throwable $e) {+ Log::error('Rybbit proxy error', ['url' => $url, 'error' => $e->getMessage()]);++ return response()->json(['error' => 'Analytics proxy error'], 502);}}}@@ -179,20 +184,64 @@ use App\Http\Controllers\AnalyticsProxyController;// Analytics proxy routesRoute::prefix('analytics')->group(function () {- // Scripts (GET)+ // Scripts (GET). Web vitals are bundled into script.js;+ // replay.js loads only when session replay is on.Route::get('/{script}', [AnalyticsProxyController::class, 'proxyScript'])- ->where('script', '(script|replay|metrics)\.js');-- // Tracking endpoints (POST)- Route::post('/track', [AnalyticsProxyController::class, 'proxyTrack']);- Route::post('/identify', [AnalyticsProxyController::class, 'proxyIdentify']);- Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxySessionReplay']);+ ->where('script', '(script|replay)\.js');// Configuration (GET)Route::get('/site/tracking-config/{siteId}', [AnalyticsProxyController::class, 'proxySiteConfig']);++ // Tracking endpoints (POST)+ Route::post('/track', [AnalyticsProxyController::class, 'proxyPost']);+ Route::post('/identify', [AnalyticsProxyController::class, 'proxyPost']);+ Route::post('/site/{siteId}/feature-flags/evaluate', [AnalyticsProxyController::class, 'proxyPost']);+ Route::post('/session-replay/record/{siteId}', [AnalyticsProxyController::class, 'proxyPost']);});```+These routes cover every endpoint the tracking script calls. If the feature flag route is missing, `rybbit.flag()` silently returns your fallback.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.++### Exclude the Routes from CSRF Protection++Routes in `routes/web.php` run Laravel's CSRF check, which rejects the tracker's POSTs with a 419. Exclude the analytics paths.++<Tabs items={['Laravel 11+', 'Laravel 10 and earlier']}>+<Tab>++```php+<?php+// bootstrap/app.php++use Illuminate\Foundation\Application;+use Illuminate\Foundation\Configuration\Middleware;++return Application::configure(basePath: dirname(__DIR__))+ // ...+ ->withMiddleware(function (Middleware $middleware) {+ $middleware->validateCsrfTokens(except: [+ 'analytics/*',+ ]);+ })+ // ...+ ->create();+```++</Tab>+<Tab>++```php+// app/Http/Middleware/VerifyCsrfToken.php+protected $except = [+ 'analytics/*',+];+```++</Tab>+</Tabs>+### Add Service Configuration (Optional)Add Rybbit configuration to `config/services.php`:@@ -223,7 +272,7 @@ Add the tracking script to your layout:<title>{{ config('app.name') }}</title>{{-- Rybbit Analytics --}}- <script src="{{ url('/analytics/script.js') }}" async data-site-id="YOUR_SITE_ID"></script>+ <script src="{{ url('/analytics/script.js') }}?siteId=YOUR_SITE_ID" defer></script></head><body>@yield('content')@@ -231,6 +280,8 @@ Add the tracking script to your layout:</html>```+Older snippets that pass the ID as `data-site-id` still work.+### Verify the Setup1. **Clear route cache** (if caching enabled):@@ -251,74 +302,28 @@ Laravel routes intercept requests to `/analytics/*` and forward them to Rybbit:1. Request to `/analytics/script.js` hits Laravel route2. Controller forwards to `https://app.rybbit.io/api/script.js`3. Response is cached (for cacheable endpoints)-4. Client IP and headers are preserved for accurate tracking+4. The browser's headers are passed through, and the visitor IP goes in `X-Forwarded-For`## Advanced Configuration-### Middleware for Rate Limiting--Create rate limiting middleware:+### Rate Limiting-```bash-php artisan make:middleware RateLimitAnalytics-```+Laravel's built-in `throttle` middleware limits requests per visitor IP. For example, 100 requests per minute:```php-<?php-// app/Http/Middleware/RateLimitAnalytics.php--namespace App\Http\Middleware;--use Closure;-use Illuminate\Cache\RateLimiter;--class RateLimitAnalytics-{- protected $limiter;-- public function __construct(RateLimiter $limiter)- {- $this->limiter = $limiter;- }-- public function handle($request, Closure $next)- {- $key = 'analytics:' . $request->ip();-- if ($this->limiter->tooManyAttempts($key, 100)) {- return response('Too Many Requests', 429);- }-- $this->limiter->hit($key, 60); // 100 requests per minute-- return $next($request);- }-}-```--Register in `app/Http/Kernel.php`:--```php-protected $routeMiddleware = [- // ... other middleware- 'rate.limit.analytics' => \App\Http\Middleware\RateLimitAnalytics::class,-];-```--Apply to routes:--```php-Route::prefix('analytics')->middleware('rate.limit.analytics')->group(function () {+Route::prefix('analytics')->middleware('throttle:100,1')->group(function () {// ... routes});```+Session replay sends batches every few seconds while recording, so don't set the limit so low that active visitors hit it.+### Custom Cache ConfigurationUse different cache drivers for analytics:```php-private function forwardRequest(string $path, string $method, Request $request)+private function cached(string $key, int $ttl, string $path, Request $request){// Use Redis for analytics caching$cache = Cache::store('redis');@@ -326,69 +331,18 @@ private function forwardRequest(string $path, string $method, Request $request)// Or use file cache// $cache = Cache::store('file');- // ... rest of the method+ // ... rest of the method, calling $cache->get() / $cache->put()}```-### Queue Large Requests--For large session replay uploads, use queues:--```bash-php artisan make:job ForwardAnalyticsData-```--```php-<?php-// app/Jobs/ForwardAnalyticsData.php--namespace App\Jobs;--use Illuminate\Bus\Queueable;-use Illuminate\Contracts\Queue\ShouldQueue;-use Illuminate\Support\Facades\Http;--class ForwardAnalyticsData implements ShouldQueue-{- use Queueable;-- protected $url;- protected $data;- protected $headers;-- public function __construct(string $url, array $data, array $headers)- {- $this->url = $url;- $this->data = $data;- $this->headers = $headers;- }-- public function handle()- {- Http::withHeaders($this->headers)- ->post($this->url, $this->data);- }-}-```+### Don't Queue Tracking Requests-Use in controller for session replay:+<Callout type="warn">+Forward every analytics request synchronously and return Rybbit's response. Don't hand session replay, `/track` or `/identify` requests to a queued job that answers right away:-```php-public function proxySessionReplay(Request $request, string $siteId)-{- // Dispatch job for async processing- ForwardAnalyticsData::dispatch(- "{$this->rybbitHost}/api/session-replay/record/{$siteId}",- $request->all(),- [- 'X-Real-IP' => $request->ip(),- 'User-Agent' => $request->header('User-Agent'),- ]- );-- return response()->json(['status' => 'queued']);-}-```+- The tracker reads the replay endpoint's response. Rybbit uses it to tell the tracker to stop recording (when a session hits the replay size cap) or to take a fresh full snapshot. A queued proxy that always answers `queued` hides both.+- A job runs outside the request, so it no longer has the browser's headers. Batches forwarded with only an IP and user agent are classified as bot traffic.+</Callout>### CORS Configuration@@ -422,29 +376,23 @@ return [**Problem**: CSRF token errors on tracking endpoints.**Solution**:-Exclude analytics routes from CSRF protection in `app/Http/Middleware/VerifyCsrfToken.php`:--```php-protected $except = [- 'analytics/*',-];-```+Exclude `analytics/*` from CSRF protection. See [Exclude the Routes from CSRF Protection](#exclude-the-routes-from-csrf-protection) for Laravel 11+ (`bootstrap/app.php`) and earlier versions.### Incorrect geolocation**Problem**: All visitors show server's location.**Solution**:-Ensure IP forwarding in controller:-```php-$clientIp = $request->header('X-Forwarded-For', $request->ip());-```+1. Enable **First-Party Proxy** in **Site Settings β Privacy & Security**.+2. Make sure the controller sets `X-Forwarded-For` to `$request->ip()`.+3. If your app runs behind a load balancer or CDN, configure Laravel's trusted proxies so `$request->ip()` returns the visitor IP rather than the load balancer's.-And add to HTTP request:-```php-'X-Real-IP' => $clientIp,-'X-Forwarded-For' => $clientIp,-```+### Events return 200 but don't appear++**Problem**: `/analytics/track` answers 200, but the dashboard stays empty.++**Solution**:+Check that the controller passes the browser's headers through. A proxy that sends only `User-Agent` and the IP looks like a script, and its events are classified as bot traffic. Also check that POST bodies are forwarded raw with `$request->getContent()`: re-encoding `$request->all()` turns empty strings into `null`, which Rybbit rejects with a 400.### Cache not clearingdiff --git a/docs/content/docs/(docs)/proxy-guide/next-js.mdx b/docs/content/docs/(docs)/proxy-guide/next-js.mdxindex bc4b9012b..42932ff25 100644--- a/docs/content/docs/(docs)/proxy-guide/next-js.mdx+++ b/docs/content/docs/(docs)/proxy-guide/next-js.mdx@@ -7,7 +7,7 @@ import { Steps } from 'fumadocs-ui/components/steps';import { Callout } from 'fumadocs-ui/components/callout';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.+Next.js provides a powerful [rewrites](https://nextjs.org/docs/app/api-reference/config/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.@@ -71,7 +71,7 @@ Add or update the `rewrites` function in your `next.config.js` (or `next.config.<Tabs items={['Full Proxy (Recommended)', 'Minimal Proxy', 'ESM (next.config.mjs)']}><Tab>-This configuration proxies all Rybbit endpoints including session replay and Web Vitals:+This configuration proxies every endpoint the tracking script calls. Web vitals are bundled into `script.js`; `replay.js` loads only when session replay is on. If the feature-flag route isn't proxied, `rybbit.flag()` silently returns your fallback.```javascript// next.config.js@@ -95,10 +95,6 @@ const nextConfig = {source: '/analytics/replay.js',destination: `${rybbitHost}/api/replay.js`,},- {- source: '/analytics/metrics.js',- destination: `${rybbitHost}/api/metrics.js`,- },// Tracking endpoints{source: '/analytics/track',@@ -116,6 +112,10 @@ const nextConfig = {source: '/analytics/site/tracking-config/:siteId',destination: `${rybbitHost}/api/site/tracking-config/:siteId`,},+ {+ source: '/analytics/site/:siteId/feature-flags/evaluate',+ destination: `${rybbitHost}/api/site/:siteId/feature-flags/evaluate`,+ },];},};@@ -126,7 +126,7 @@ module.exports = nextConfig;</Tab><Tab>-Minimal setup with just script loading and basic event tracking:+Minimal setup with just the script and the event endpoint:```javascript// next.config.js@@ -157,7 +157,7 @@ module.exports = nextConfig;```<Callout type="warn">-This minimal setup won't support session replay or Web Vitals. Use the full proxy configuration if you need these features.+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults: pageviews, SPA navigation, query strings and outbound links are tracked; web vitals, error tracking, session replay, button clicks, copy and form tracking stay off; feature flags return their fallback; and `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user. Use the full proxy unless that's what you want.</Callout></Tab>@@ -190,10 +190,6 @@ const nextConfig = {source: '/analytics/replay.js',destination: `${rybbitHost}/api/replay.js`,},- {- source: '/analytics/metrics.js',- destination: `${rybbitHost}/api/metrics.js`,- },{source: '/analytics/identify',destination: `${rybbitHost}/api/identify`,@@ -206,6 +202,10 @@ const nextConfig = {source: '/analytics/site/tracking-config/:siteId',destination: `${rybbitHost}/api/site/tracking-config/:siteId`,},+ {+ source: '/analytics/site/:siteId/feature-flags/evaluate',+ destination: `${rybbitHost}/api/site/:siteId/feature-flags/evaluate`,+ },];},};@@ -218,11 +218,13 @@ export default nextConfig;<Callout type="info">**Custom Path**: You can change `/analytics` to any path you prefer (e.g., `/tracking`, `/stats`, `/rybbit`). Just ensure you use the same path consistently in both your rewrites and script tag.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.</Callout>### Update Your Tracking Script-Update your script tag to load from the proxied path instead of directly from Rybbit:+Update your script tag to load from the proxied path instead of directly from Rybbit. The site ID goes in the script URL; older snippets that pass it as `data-site-id` still work.<Tabs items={['App Router (Next.js 13+)', 'Pages Router', 'JavaScript (No TypeScript)']}><Tab>@@ -243,8 +245,7 @@ export default function RootLayout({<body>{children}<Script- src="/analytics/script.js"- data-site-id="YOUR_SITE_ID"+ src="/analytics/script.js?siteId=YOUR_SITE_ID"strategy="afterInteractive"/></body>@@ -270,8 +271,7 @@ function MyApp({ Component, pageProps }: AppProps) {<><Component {...pageProps} /><Script- src="/analytics/script.js"- data-site-id="YOUR_SITE_ID"+ src="/analytics/script.js?siteId=YOUR_SITE_ID"strategy="afterInteractive"/></>@@ -296,8 +296,7 @@ export default function RootLayout({ children }) {<body>{children}<Script- src="/analytics/script.js"- data-site-id="YOUR_SITE_ID"+ src="/analytics/script.js?siteId=YOUR_SITE_ID"strategy="afterInteractive"/></body>@@ -346,7 +345,7 @@ Open your website in a browser with Developer Tools:The Rybbit tracking script has a built-in auto-discovery mechanism. When it loads from:```html-<script src="/analytics/script.js" data-site-id="123"></script>+<script src="/analytics/script.js?siteId=123" defer></script>```It automatically extracts the analytics host from its own `src` attribute:@@ -356,7 +355,7 @@ It automatically extracts the analytics host from its own `src` attribute:const scriptElement = document.currentScript;const src = scriptElement.getAttribute('src');const analyticsHost = src.split('/script.js')[0];-// Result: "" (empty string means same domain)+// Result: "/analytics" (a relative path, so requests stay on your domain)```This means all tracking requests automatically go to `/analytics/track`, `/analytics/identify`, etc., which Next.js then rewrites to forward to Rybbit's servers.@@ -381,8 +380,8 @@ Next.js automatically caches responses when possible, but you can optimize furthIf deployed on Vercel, your rewrites benefit from the global Edge Network, which caches static scripts close to users worldwide.**Custom caching headers:**-The Rybbit server sets cache headers on its scripts, which Next.js respects:-- Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`, `metrics.js`)+The Rybbit server sets cache headers on its scripts, which Next.js passes through:+- Scripts (`.js` files): Cached for 1 hour (`script.js`) to 1 day (`replay.js`)- Configuration: Not cached by the server (you may cache it for ~5 minutes at your proxy if desired)- Tracking POSTs: Not cached@@ -491,7 +490,7 @@ const nextConfig = {};```-### Conditional proxy (development only)+### Conditional proxy (production only)If you only want proxying in production:@@ -513,4 +512,4 @@ const nextConfig = {- [Next.js Integration Guide](/docs/guides/react/next-js) - General Next.js integration- [Tracking Script Documentation](/docs/script) - Script configuration options- [Custom Events](/docs/track-events) - Track custom events-- [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/next-config-js/rewrites) - Official Next.js docs+- [Next.js Rewrites Documentation](https://nextjs.org/docs/app/api-reference/config/next-config-js/rewrites) - Official Next.js docsdiff --git a/docs/content/docs/(docs)/proxy-guide/nginx.mdx b/docs/content/docs/(docs)/proxy-guide/nginx.mdxindex 5ec73a70f..7803eea1e 100644--- a/docs/content/docs/(docs)/proxy-guide/nginx.mdx+++ b/docs/content/docs/(docs)/proxy-guide/nginx.mdx@@ -62,7 +62,9 @@ server {}# Rybbit Analytics Proxy- # Main tracking script (cached)+ # nginx passes the browser's other request headers through unchanged.++ # Main tracking scriptlocation = /analytics/script.js {proxy_pass https://app.rybbit.io/api/script.js;proxy_set_header Host app.rybbit.io;@@ -70,14 +72,9 @@ server {proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;proxy_ssl_server_name on;-- # Cache for 1 hour- proxy_cache_valid 200 1h;- proxy_cache_bypass $http_cache_control;- add_header X-Cache-Status $upstream_cache_status;}- # Session replay script (cached)+ # Session replay script (loaded only when session replay is on)location = /analytics/replay.js {proxy_pass https://app.rybbit.io/api/replay.js;proxy_set_header Host app.rybbit.io;@@ -85,20 +82,6 @@ server {proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;proxy_ssl_server_name on;-- proxy_cache_valid 200 1h;- }-- # Web Vitals metrics script (cached)- location = /analytics/metrics.js {- proxy_pass https://app.rybbit.io/api/metrics.js;- proxy_set_header Host app.rybbit.io;- proxy_set_header X-Real-IP $remote_addr;- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;- proxy_set_header X-Forwarded-Proto $scheme;- proxy_ssl_server_name on;-- proxy_cache_valid 200 1h;}# Event tracking endpoint (not cached)@@ -108,7 +91,6 @@ server {proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header Content-Type application/json;proxy_ssl_server_name on;}@@ -119,47 +101,59 @@ server {proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header Content-Type application/json;proxy_ssl_server_name on;}- # Session replay recording endpoint (not cached)- location ~ ^/analytics/session-replay/record/(.*)$ {- proxy_pass https://app.rybbit.io/api/session-replay/record/$1;+ # Site configuration endpoint+ location /analytics/site/tracking-config/ {+ proxy_pass https://app.rybbit.io/api/site/tracking-config/;proxy_set_header Host app.rybbit.io;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;- proxy_set_header Content-Type application/json;proxy_ssl_server_name on;+ }- # Allow larger uploads for session replay- client_max_body_size 10M;+ # Feature flag evaluation (not cached)+ location ~ ^/analytics/site/[^/]+/feature-flags/evaluate$ {+ rewrite ^/analytics/(.*)$ /api/$1 break;+ proxy_pass https://app.rybbit.io;+ proxy_set_header Host app.rybbit.io;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_ssl_server_name on;}- # Site configuration endpoint (cached briefly)- location ~ ^/analytics/site/tracking-config/(.*)$ {- proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;+ # Session replay recording endpoint (not cached)+ location /analytics/session-replay/record/ {+ proxy_pass https://app.rybbit.io/api/session-replay/record/;proxy_set_header Host app.rybbit.io;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header X-Forwarded-Proto $scheme;proxy_ssl_server_name on;- # Cache for 5 minutes- proxy_cache_valid 200 5m;+ # Allow larger uploads for session replay+ client_max_body_size 10M;}}```+This covers every endpoint the tracking script calls. Web vitals are bundled into `script.js`; `replay.js` loads only when session replay is on. If the feature-flag route isn't proxied, `rybbit.flag()` silently returns your fallback.+<Callout type="info">Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.</Callout>+<Callout type="warn">+Keep variables out of `proxy_pass`. With a variable such as `$1`, nginx resolves the upstream hostname per request and returns `502` unless you configure a `resolver`. And in a regex location (`location ~`), a `proxy_pass` with a fixed path such as `/api/track` fails `nginx -t`; only a path built from variables is allowed there, and that brings back the `resolver` requirement. That's why the paths with a site ID use prefix locations, or a `rewrite` followed by a `proxy_pass` without a path.+</Callout>+</Tab><Tab>-Minimal configuration for basic tracking:+Minimal configuration with just the script and the event endpoint:```nginx# /etc/nginx/sites-available/yourdomain.com@@ -178,8 +172,6 @@ server {proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_ssl_server_name on;-- proxy_cache_valid 200 1h;}# Event tracking@@ -193,10 +185,14 @@ server {}```+<Callout type="warn">+A minimal setup proxies only `script.js` and `/track`. The script then can't fetch your site's tracking config, so it ignores every setting on the site's **Tracking** tab and runs on built-in defaults: pageviews, SPA navigation, query strings and outbound links are tracked; web vitals, error tracking, session replay, button clicks, copy and form tracking stay off; feature flags return their fallback; and `identify()` and `setTraits()` can't reach `/identify`, so traits aren't stored and earlier anonymous activity isn't linked to the user. Use the full proxy unless that's what you want.+</Callout>+</Tab><Tab>-For better performance with caching, define a cache zone:+The other tabs don't cache anything: `proxy_cache_valid` has no effect without a `proxy_cache` zone. To cache the scripts at your proxy, define a cache zone:```nginx# /etc/nginx/nginx.conf (http block)@@ -213,7 +209,7 @@ http {}```-Then in your site config:+Then add the cache directives to the script locations in your site config:```nginx# /etc/nginx/sites-available/yourdomain.com@@ -238,6 +234,8 @@ server {}```+Do the same for `replay.js`. If you also cache `/analytics/site/tracking-config/`, keep it short (`proxy_cache_valid 200 5m;`) so changes you make in the dashboard reach visitors. Never cache the POST endpoints.+</Tab></Tabs>@@ -290,7 +288,7 @@ Update your HTML to load the script from your proxied domain:<html><head><!-- ... other head elements -->- <script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+ <script src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script></head><body><!-- Your content -->@@ -298,7 +296,9 @@ Update your HTML to load the script from your proxied domain:</html>```-Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard.+Replace `YOUR_SITE_ID` with your actual site ID from the Rybbit dashboard. Older snippets that pass the ID as `data-site-id` still work.++Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.### Verify the Setup@@ -318,10 +318,10 @@ Test your configuration:```HTTP/2 200content-type: application/javascript- x-cache-status: MISS # First request+ x-cache-status: MISS # First request, only if you set up the cache zone```-3. **Test again to verify caching**:+3. **If you set up the cache zone, test again to verify caching**:```bashcurl -I https://yourdomain.com/analytics/script.js```@@ -355,27 +355,31 @@ The Rybbit script auto-detects it's being served from your domain and sends all### Caching Strategy-Configure different cache durations based on content type:+Configure different cache durations based on content type (requires the cache zone from the **With Cache Zone** tab). These blocks replace the matching ones from the **Full Proxy** tab; don't add them alongside. nginx picks an exact-match `location =` over a regex one, and a repeated prefix location fails `nginx -t`.```nginx-# Scripts - cache for 1 hour-location ~ ^/analytics/(script|replay|metrics)\.js$ {- proxy_pass https://app.rybbit.io/api/$1.js;+# Scripts - nginx follows Rybbit's Cache-Control: 1 hour for script.js, 1 day for replay.js+location ~ ^/analytics/(script|replay)\.js$ {+ rewrite ^/analytics/(.*)$ /api/$1 break;+ proxy_pass https://app.rybbit.io;# ... proxy headers+ proxy_cache rybbit_cache;proxy_cache_valid 200 1h;proxy_cache_valid 404 1m; # Cache 404s briefly}# Config - cache for 5 minutes (changes when you update dashboard settings)-location ~ ^/analytics/site/tracking-config/(.*)$ {- proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;+location /analytics/site/tracking-config/ {+ proxy_pass https://app.rybbit.io/api/site/tracking-config/;# ... proxy headers+ proxy_cache rybbit_cache;proxy_cache_valid 200 5m;}# Tracking - never cache (each request is unique)location ~ ^/analytics/(track|identify)$ {- proxy_pass https://app.rybbit.io/api/$1;+ rewrite ^/analytics/(.*)$ /api/$1 break;+ proxy_pass https://app.rybbit.io;# ... proxy headers# No caching directives}@@ -407,6 +411,10 @@ location /analytics/ {proxy_pass https://rybbit_backend/api/;proxy_http_version 1.1;proxy_set_header Connection "";+ # With an upstream block, Host and SNI default to "rybbit_backend"+ proxy_set_header Host app.rybbit.io;+ proxy_ssl_server_name on;+ proxy_ssl_name app.rybbit.io;# ... other proxy headers}```@@ -416,7 +424,7 @@ location /analytics/ {For better performance with larger session replay uploads:```nginx-location ~ ^/analytics/session-replay/record/ {+location /analytics/session-replay/record/ {proxy_pass https://app.rybbit.io/api/session-replay/record/;# ... proxy headers@@ -461,7 +469,7 @@ Set appropriate limits for different endpoints:client_max_body_size 1M;# Larger limit for session replay-location ~ ^/analytics/session-replay/record/ {+location /analytics/session-replay/record/ {client_max_body_size 10M;# ... proxy config}@@ -489,11 +497,26 @@ add_header Referrer-Policy strict-origin-when-cross-origin;curl -I https://app.rybbit.io/api/script.js```2. Verify `proxy_ssl_server_name on` is set-3. Check Nginx error logs:+3. If the error log says `no resolver defined to resolve app.rybbit.io`, a `proxy_pass` contains a variable (such as `$1`). Remove the variable (use a prefix location, or `rewrite ... break` with a `proxy_pass` that has no path), or add a `resolver` directive+4. Check Nginx error logs:```bashsudo tail -f /var/log/nginx/error.log```+### `nginx -t` fails on a regex location++**Problem**: `nginx -t` reports `"proxy_pass" cannot have URI part in location given by regular expression`.++**Solution**: A `location ~` block can't use a `proxy_pass` with a fixed path such as `/api/...` (a path built from variables is allowed, but then nginx needs a `resolver`). Use a prefix location (`location /analytics/session-replay/record/`), or keep the regex and rewrite the URI first:++```nginx+location ~ ^/analytics/site/[^/]+/feature-flags/evaluate$ {+ rewrite ^/analytics/(.*)$ /api/$1 break;+ proxy_pass https://app.rybbit.io;+ # ... proxy headers+}+```+### Cache not working**Problem**: `X-Cache-Status` always shows `MISS`.@@ -512,7 +535,7 @@ add_header Referrer-Policy strict-origin-when-cross-origin;**Problem**: All visitors show same location (your server's location).**Solution**:-Ensure you're forwarding client IP headers:+Ensure you're forwarding client IP headers, and that **First-Party Proxy** is on in your site settings:```nginxproxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;@@ -560,7 +583,7 @@ server {Then use:```html-<script src="https://analytics.yourdomain.com/script.js" data-site-id="123"></script>+<script src="https://analytics.yourdomain.com/script.js?siteId=123" defer></script>```### Multiple Rybbit Instancesdiff --git a/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx b/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdxindex 33e793ca4..e9bb334ab 100644--- a/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx+++ b/docs/content/docs/(docs)/proxy-guide/troubleshooting.mdx@@ -43,6 +43,7 @@ Your domain β Rybbit backendCommon mistakes:- Wrong source path (`/tracking` instead of `/analytics`)- Incorrect destination (missing `/api` prefix)+- A renamed script file. Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.- Typos in configuration### Test Direct Backend Access@@ -104,32 +105,55 @@ app.get('*', (req, res) => res.sendFile('index.html'));### Verify All Endpoints Are Proxied-Ensure tracking endpoints are configured:+Ensure every endpoint the script calls is configured:-- `/analytics/track` (required)-- `/analytics/identify` (for user identification)-- `/analytics/session-replay/record/:siteId` (for session replay)-- `/analytics/site/tracking-config/:siteId` (for configuration)+| Your path | Rybbit endpoint | Without it |+|-----------|-----------------|------------|+| `/analytics/script.js` (GET) | `/api/script.js` | Nothing loads |+| `/analytics/track` (POST) | `/api/track` | No events |+| `/analytics/site/tracking-config/:siteId` (GET) | `/api/site/tracking-config/:siteId` | Every setting on the site's **Tracking** tab is ignored and the script runs on built-in defaults: web vitals, error tracking, session replay, button clicks, copy and form tracking stay off |+| `/analytics/identify` (POST) | `/api/identify` | `identify()` and `setTraits()` fail, so traits aren't stored and earlier anonymous activity isn't linked to the user |+| `/analytics/site/:siteId/feature-flags/evaluate` (POST) | `/api/site/:siteId/feature-flags/evaluate` | `rybbit.flag()` silently returns your fallback |+| `/analytics/replay.js` (GET) | `/api/replay.js` | Session replay can't start (loaded only when replay is on) |+| `/analytics/session-replay/record/:siteId` (POST) | `/api/session-replay/record/:siteId` | Replays aren't saved |-**Check Network tab**: Look for failed POST requests to `/analytics/track`.+Web vitals are bundled into `script.js`, so there's no separate metrics script to proxy.-### Check CORS Headers+**Check Network tab**: Look for failed requests to any `/analytics/*` path.-Tracking endpoints need proper CORS headers. Rybbit sets these automatically, but ensure your proxy preserves them:+### Don't Let a Body Parser Run Before the Proxy-```nginx-# Nginx - preserve CORS headers-proxy_pass_header Access-Control-Allow-Origin;-proxy_pass_header Access-Control-Allow-Methods;+In Express, `app.use(express.json())` registered before the proxy reads the request body first, so the proxy forwards an empty body and `/track`, `/identify` and session replay POSTs fail. Mount the proxy before any body parser, or use http-proxy-middleware's `fixRequestBody`:++```javascript+const { createProxyMiddleware, fixRequestBody } = require('http-proxy-middleware');++// β Proxy first, body parsers after+app.use('/analytics', createProxyMiddleware({+ target: 'https://app.rybbit.io/api',+ changeOrigin: true,+}));+app.use(express.json());++// Or, if a body parser must run first:+app.use('/analytics', createProxyMiddleware({+ target: 'https://app.rybbit.io/api',+ changeOrigin: true,+ on: { proxyReq: fixRequestBody },+}));```+### Check CORS Headers++CORS only matters when the script is served from a different origin than your pages (for example an `analytics.` subdomain). Rybbit sets the CORS headers itself, echoing the page's origin back in `Access-Control-Allow-Origin`, and Nginx passes them through by default. Don't add or override them in your proxy:+```javascript-// Express - don't override CORS-// β Wrong - blocks CORS+// Express+// β Wrong - a cors() middleware in front of the proxy replaces Rybbit's headersapp.use('/analytics', cors({ origin: 'https://yourdomain.com' }));-// β Correct - allow all origins (or use Rybbit's headers)-app.use('/analytics', cors({ origin: true }));+// β Correct - no cors() on the proxy path; Rybbit's headers pass through+app.use('/analytics', createProxyMiddleware({ target: 'https://app.rybbit.io/api', changeOrigin: true }));```### Verify Content-Type for POST Requests@@ -142,12 +166,12 @@ proxy_set_header Content-Type $content_type;``````javascript-// Express-onProxyReq: (proxyReq, req) => {- if (req.headers['content-type']) {- proxyReq.setHeader('Content-Type', req.headers['content-type']);- }-}+// Express (http-proxy-middleware v3 forwards Content-Type as-is;+// v3 replaced the old onProxyReq option with on.proxyReq)+createProxyMiddleware({+ target: 'https://app.rybbit.io/api',+ changeOrigin: true,+});```### Check Request Method Preservation@@ -188,22 +212,28 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;proxy_set_header User-Agent $http_user_agent;```-**Caddy:**+**Caddy (2.7 or later):**```txtreverse_proxy https://app.rybbit.io {- header_up X-Real-IP {remote_host}- header_up X-Forwarded-For {remote_host}+ header_up X-Real-IP {client_ip}+ header_up X-Forwarded-For {client_ip}}```-**Express:**+If a CDN sits in front of Caddy, add its IP ranges to the `trusted_proxies` global option, or `{client_ip}` is the CDN's edge server. See the [Caddy guide](/docs/proxy-guide/caddy).++**Express (http-proxy-middleware v3):**```javascript-onProxyReq: (proxyReq, req) => {- const clientIp = req.headers['x-forwarded-for'] || req.socket.remoteAddress;- proxyReq.setHeader('X-Real-IP', clientIp);- proxyReq.setHeader('X-Forwarded-For', clientIp);- proxyReq.setHeader('User-Agent', req.headers['user-agent']);-}+createProxyMiddleware({+ target: 'https://app.rybbit.io/api',+ changeOrigin: true,+ on: {+ proxyReq: (proxyReq, req) => {+ // With app.set('trust proxy', ...) configured, req.ip is the visitor IP+ proxyReq.setHeader('X-Forwarded-For', req.ip);+ },+ },+});```**Cloudflare Workers:**@@ -221,7 +251,9 @@ proxyHeaders.set('X-Forwarded-For', clientIp);- 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.+A `200` from `/track` doesn't prove an event was stored. Rybbit also answers `200` when the event is diverted as bot traffic, matches a site exclusion, or belongs to a site that's over its monthly limit or has no plan. See [Script troubleshooting](/docs/script-troubleshooting) for the non-proxy causes.++There are two independent causes on the proxy side, and server-side proxies often hit **both**. Work through them in order.#### Cause 1: Your proxy strips the browser's headers@@ -311,24 +343,25 @@ Session replay can send large payloads (up to 10MB). Ensure your proxy allows th```nginx# Nginx-location ~ ^/analytics/session-replay/record/ {+location /analytics/session-replay/record/ {client_max_body_size 10M;- proxy_pass https://app.rybbit.io;+ proxy_pass https://app.rybbit.io/api/session-replay/record/;}``````javascript-// Express-app.use('/analytics/session-replay', express.json({ limit: '10mb' }));+// Express: don't parse replay bodies before the proxy at all.+// The proxy streams them through, so no size option is needed.+// See "Don't Let a Body Parser Run Before the Proxy" above.``````javascript-// Next.js - add to next.config.js+// Next.js: rewrites stream the body through. Only if your app has a+// proxy.ts (middleware) file does Next.js buffer request bodies, capped+// at 10 MB by default. Raise that cap in next.config.js if needed:module.exports = {- api: {- bodyParser: {- sizeLimit: '10mb',- },+ experimental: {+ proxyClientMaxBodySize: '10mb',},};```@@ -352,9 +385,10 @@ module.exports = {```nginx# Nginx - cache for 5 minutes max-location ~ ^/analytics/site/tracking-config/(.*)$ {+location /analytics/site/tracking-config/ {+ proxy_cache rybbit;proxy_cache_valid 200 5m; # Not longer!- proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;+ proxy_pass https://app.rybbit.io/api/site/tracking-config/;}```@@ -380,9 +414,9 @@ cache.flushAll();```nginx# Nginx - no caching-location ~ ^/analytics/site/tracking-config/(.*)$ {+location /analytics/site/tracking-config/ {proxy_cache off;- proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;+ proxy_pass https://app.rybbit.io/api/site/tracking-config/;}```@@ -424,20 +458,22 @@ sudo nginx -s reload// Caching β Configuration β Purge Everything```-3. **Add cache busting** (advanced):+3. **Set the browser cache lifetime explicitly** (advanced). Rybbit already serves `script.js` with `max-age=3600`; set it yourself only if something in your stack changes that header:```javascript-// Next.js - revalidate on each deployment-{- source: '/analytics/script.js',- destination: `${rybbitHost}/api/script.js`,- headers: [- {- key: 'Cache-Control',- value: 'public, max-age=3600, must-revalidate',- },- ],-}+// Next.js - rewrites can't set headers; use headers() alongside rewrites()+module.exports = {+ async headers() {+ return [+ {+ source: '/analytics/script.js',+ headers: [+ { key: 'Cache-Control', value: 'public, max-age=3600, must-revalidate' },+ ],+ },+ ];+ },+};```---@@ -597,17 +633,22 @@ async rewrites() {proxy_ssl_server_name on;```-2. **Check DNS resolution**:+2. **Add a `resolver`** if `proxy_pass` uses a variable (for example `proxy_pass https://app.rybbit.io/api/site/tracking-config/$1;` in a regex location). Nginx resolves variable upstreams at request time and returns 502 without one:+```nginx+resolver 1.1.1.1 8.8.8.8 valid=300s;+```++3. **Check DNS resolution**:```bashnslookup app.rybbit.io```-3. **Check logs**:+4. **Check logs**:```bashsudo tail -f /var/log/nginx/error.log```-4. **Test backend directly**:+5. **Test backend directly**:```bashcurl -v https://app.rybbit.io/api/script.js```@@ -638,7 +679,10 @@ git pushWhen troubleshooting, work through this checklist:- [ ] Script loads successfully (200 status, correct Content-Type)+- [ ] Proxied file is still named `script.js`- [ ] Tracking endpoint is proxied (`/analytics/track`)+- [ ] Config, identify and feature flag endpoints are proxied (`/analytics/site/tracking-config/:siteId`, `/analytics/identify`, `/analytics/site/:siteId/feature-flags/evaluate`)+- [ ] No body parser consumes POST bodies before the proxy- [ ] POST requests preserve method and body- [ ] 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 & Securitydiff --git a/docs/content/docs/(docs)/proxy-guide/vercel.mdx b/docs/content/docs/(docs)/proxy-guide/vercel.mdxindex eb2f94064..d555e2ae6 100644--- a/docs/content/docs/(docs)/proxy-guide/vercel.mdx+++ b/docs/content/docs/(docs)/proxy-guide/vercel.mdx@@ -51,10 +51,6 @@ Add rewrites to your `vercel.json` file in the project root:"source": "/analytics/replay.js","destination": "https://app.rybbit.io/api/replay.js"},- {- "source": "/analytics/metrics.js",- "destination": "https://app.rybbit.io/api/metrics.js"- },{"source": "/analytics/track","destination": "https://app.rybbit.io/api/track"@@ -70,23 +66,35 @@ Add rewrites to your `vercel.json` file in the project root:{"source": "/analytics/site/tracking-config/:siteId","destination": "https://app.rybbit.io/api/site/tracking-config/:siteId"+ },+ {+ "source": "/analytics/site/:siteId/feature-flags/evaluate",+ "destination": "https://app.rybbit.io/api/site/:siteId/feature-flags/evaluate"}]}```+This covers every endpoint the tracking script calls. Web vitals are bundled into `script.js`; `replay.js` loads only when session replay is on. If the feature-flag route isn't proxied, `rybbit.flag()` silently returns your fallback.+<Callout type="info">Replace `app.rybbit.io` with your self-hosted Rybbit instance URL if you're not using the cloud version.</Callout>+<Callout type="warn">+Keep the proxied file named `script.js`. The script cuts its own URL at `/script.js` to find where to send events, so a renamed file (for example `/analytics/a.js`) sends every request to the wrong place.+</Callout>+### Update Your Tracking ScriptUpdate your HTML to use the proxied path:```html-<script src="/analytics/script.js" async data-site-id="YOUR_SITE_ID"></script>+<script src="/analytics/script.js?siteId=YOUR_SITE_ID" defer></script>```+Older snippets that pass the site ID as `data-site-id` still work.+### Deploy to VercelCommit your changes and deploy:@@ -116,8 +124,8 @@ Vercel's Edge Network handles rewrites at the edge, close to your users:1. Request hits Vercel's edge location nearest to the user2. Edge server rewrites and proxies to Rybbit-3. Response is cached at the edge (for cacheable requests)-4. Subsequent requests serve from edge cache+3. Responses Rybbit marks as cacheable (the scripts) can be cached at the edge+4. Subsequent requests for those scripts are served from the edge cacheThis provides excellent performance with minimal configuration.@@ -125,11 +133,11 @@ This provides excellent performance with minimal configuration.### Edge Network Caching-Vercel automatically caches responses at edge locations:+Vercel caches external rewrites according to the upstream `Cache-Control` header. That's the default for projects created on or after April 6, 2026; older projects need to opt in (see [Vercel's rewrite caching docs](https://vercel.com/docs/routing/rewrites#caching-rewrites-to-external-origins)).-- **Scripts**: Cached globally, served from nearest edge-- **Configuration**: Cached with appropriate TTL-- **Tracking requests**: Not cached (unique per request)+- **Scripts**: Rybbit sends `Cache-Control` on `script.js` (1 hour) and `replay.js` (1 day), so they can be served from the nearest edge+- **Configuration**: Rybbit sends no cache headers for `tracking-config`, so it isn't cached+- **Tracking requests**: Not cached (POSTs, unique per request)### Global Distribution@@ -168,6 +176,8 @@ Check your Vercel plan limits. Pro plan includes 1 TB bandwidth/month.Verify all endpoints are in `vercel.json` rewrites, including:- `/analytics/track`- `/analytics/identify`+- `/analytics/site/tracking-config/:siteId`+- `/analytics/site/:siteId/feature-flags/evaluate`- `/analytics/session-replay/record/:siteId`### Session replay not working@@ -238,7 +248,7 @@ Add custom headers to responses:],"headers": [{- "source": "/analytics/(.*)",+ "source": "/analytics/script.js","headers": [{"key": "Cache-Control",@@ -280,4 +290,4 @@ Don't use redirects for proxying (they're visible to the user):- [Next.js Proxy Guide](/docs/proxy-guide/next-js) - If using Next.js- [Tracking Script Documentation](/docs/script) - Script configuration-- [Vercel Rewrites Documentation](https://vercel.com/docs/projects/project-configuration#rewrites) - Official Vercel docs+- [Vercel Rewrites Documentation](https://vercel.com/docs/routing/rewrites) - Official Vercel docsdiff --git a/docs/content/docs/(docs)/script-troubleshooting.mdx b/docs/content/docs/(docs)/script-troubleshooting.mdxindex a41ce3a96..a4a0e8f04 100644--- a/docs/content/docs/(docs)/script-troubleshooting.mdx+++ b/docs/content/docs/(docs)/script-troubleshooting.mdx@@ -28,17 +28,20 @@ Alternatively, you can use keyboard shortcuts:In the console, type `rybbit` and press Enter.-**If the script is loaded correctly**, you'll see an object with functions like this:-```javascript-{event: Ζ, pageview: Ζ, identify: Ζ, setTraits: Ζ, clearUserId: Ζ, β¦}-```--**If the script is NOT loaded**, you'll see an error like:+**If you see an error** like the one below, the script didn't load at all. Continue reading for common causes.```Uncaught ReferenceError: rybbit is not defined```-If you see the error, the script is not loading properly. Continue reading for common causes.+**If you see an object** with functions like `{event: Ζ, pageview: Ζ, identify: Ζ, β¦}`, the script file loaded, but that doesn't prove tracking works. The script creates this object before it reads its configuration, and it stays a placeholder that queues your calls if the site ID is missing. Browsers that opted out (see [Hiding your own traffic](/docs/hiding-own-traffic)) get an object whose functions do nothing.+</Step>++<Step>+### Check the Console and Network Tab++Look in the console for messages from the script, such as `Please provide a valid site ID using the ?siteId= query parameter or the data-site-id attribute` or `Failed to fetch tracking config from API, using defaults`.++Then open the **Network** tab and reload the page. A working install makes a request to `/site/tracking-config/YOUR_SITE_ID` followed by `POST` requests to `/track`. If you see neither, the script stopped before tracking anything.</Step></Steps>@@ -131,19 +134,22 @@ In single-page applications (React, Vue, Next.js, etc.), if the script loads aft**Solution:** Ensure the script is in your root HTML template (like `index.html` or `_document.js` in Next.js), not dynamically imported in a component.-For Next.js specifically, see our [Next.js Guide](/docs/guides/nextjs).+For Next.js specifically, see our [Next.js Guide](/docs/guides/react/next-js).## Testing Your InstallationOnce you've made changes, verify that tracking is working:-1. **Check the console**: Type `rybbit` to confirm the object exists-2. **Trigger a test event**: In the console, run:+1. **Trigger a test event**: In the console, run:```javascriptrybbit.event("test_event")```+2. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track", and look at the request and its response3. **Check your dashboard**: Navigate to the Events tab in your Rybbit dashboard and look for "test_event" (it may take a few seconds to appear)-4. **Check the Network tab**: In browser dev tools, go to the Network tab, filter by "track" or "rybbit", and verify requests are being sent with 200 status codes++<Callout type="warn">+A `200` response from `/track` doesn't mean the event was stored. Excluded, bot-classified, over-limit and no-plan events all get `200`. Read the response body: `{"success":true}` means accepted (unless the hit was classified as a bot), a `message` field means an exclusion matched, and a plain-text body means the site is over its limit or has no plan. The dashboard is the real test.+</Callout>## Still Having Issues?@@ -151,8 +157,10 @@ If you've tried all the above and are still not seeing traffic:1. **Check the browser Network tab** for any failed requests to your Rybbit instance2. **Verify your site ID** is correct in the dashboard-3. **Check if traffic is being filtered** - review your [IP exclusions](/docs/hiding-own-traffic) and [country exclusions](/docs/filter-traffic) to ensure your traffic isn't being blocked-4. **For self-hosted instances** - ensure your Rybbit server is running and accessible+3. **Check if traffic is being filtered**: review the site's [exclusions](/docs/filter-traffic) (IP, country, ASN, path, query parameter, hostname and user agent) and [your own traffic settings](/docs/hiding-own-traffic)+4. **Check bot detection**: hits from headless browsers and automation tools (Puppeteer, Playwright, Selenium) are classified as bots and, with bot blocking on, stored as bot traffic instead of analytics. A cloud or hosting network (a VPN, a CI runner, a cloud desktop) doesn't convict a hit on its own, but it counts against a hit that already looks automated. Test from a normal browser. See [Bot Detection](/docs/bot-detection).+5. **Check your plan and usage** (Rybbit Cloud): once a site passes its monthly event limit, new events are dropped until the next month or an upgrade. Sites created on or after February 13, 2026 collect nothing while their organization has no trial or paid plan. After a trial ends unpaid, the organization's sites keep collecting for 60 days, then stop.+6. **For self-hosted instances**: ensure your Rybbit server is running and accessible---diff --git a/docs/content/docs/(docs)/script.mdx b/docs/content/docs/(docs)/script.mdxindex 3f72d4667..7e84b97b1 100644--- a/docs/content/docs/(docs)/script.mdx+++ b/docs/content/docs/(docs)/script.mdx@@ -11,7 +11,7 @@ To start tracking user activity on your website, add the Rybbit tracking scriptThe webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.```html-<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" async></script>+<script src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID" defer></script>```If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.@@ -30,21 +30,32 @@ Most tracking options are configured through your site settings in the Rybbit da- **Automatic Initial Pageview**: Track the first pageview when the script loads- **SPA Navigation**: Automatically track navigation in single-page applications- **URL Parameters**: Include or exclude query strings from tracked URLs+- **URL Fragments**: Track ordinary `#fragments` as part of the path (see [Hash routes and URL fragments](#hash-routes-and-url-fragments))- **Outbound Links**: Track clicks to external websites+- **Button Clicks**: Track clicks on buttons+- **Copy**: Track when visitors copy text+- **Form Interactions**: Track form submissions and input changes- **Error Tracking**: Capture JavaScript errors and unhandled promise rejections- **Session Replay**: Record user interactions for debugging and UX analysis- **Web Vitals**: Collect Core Web Vitals performance metrics+If the script can't load these settings (for example, a proxy that doesn't forward `/site/tracking-config/:siteId`), it uses built-in defaults: pageviews, SPA navigation, query strings and outbound links on, everything else off.+### Script AttributesThese are the attributes you can pass to the script tag.| Attribute | Type | Default | Description || :---------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `data-skip-patterns` | `string` | `[]` | A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`. |-| `data-mask-patterns` | `string` | `[]` | A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. |+| `data-skip-patterns` | `string` | `[]` | A JSON string array of URL path patterns to ignore. On matching paths the script sends no events of any kind: pageviews, custom events, errors, web vitals and the rest. Supports two types of wildcards: `*` (matches within a segment) and `**` (matches across segments), plus regex patterns prefixed with `re:`. |+| `data-mask-patterns` | `string` | `[]` | A JSON string array of URL path patterns to mask for privacy. Events on matching paths are tracked, but the path is replaced with the pattern itself. The query string and referrer are sent unchanged. Supports the same wildcards and `re:` regex patterns as `data-skip-patterns`. || `data-debounce` | `string` | `"500"`| The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing. |-| `data-tag` | `string` | `""` | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters. See [Tagging](/docs/tagging). |+| `data-tag` | `string` | `""` | A label applied to all events from this script instance. Useful for A/B testing, deploy versioning, or cohort segmentation. Max 256 characters: the script doesn't shorten it, and a longer tag makes every event fail with `400`. See [Tagging](/docs/tagging). |+| `data-namespace` | `string` | `"rybbit"` | Renames the global object (`window.rybbit` becomes `window.<namespace>`), the opt-out key (`disable-<namespace>`) and the script's `localStorage` keys. Use it when two scripts share a page. |++<Callout type="warn">+Skip and mask patterns apply to events only. Session replay ignores both and records the full page URL, query string included. Feature flag evaluation also sends the real path. To keep page content out of replays, use the replay block and mask attributes below.+</Callout>{/* ### Feature Flags@@ -84,6 +95,9 @@ These attributes configure rrweb session replay behavior. They only apply when s| Attribute | Type | Default | Description || :---------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `data-replay-sample-rate` | `number` | `100` | Percentage of sessions to record, `0`-`100`. The decision is made once per browser session. |+| `data-replay-batch-size` | `number` | `250` | Number of recorded events that triggers an upload. |+| `data-replay-batch-interval` | `number` | `5000` | Milliseconds between uploads. Values below `1000` are raised to `1000`. || `data-replay-mask-text-selectors` | `string` | `[]` | A JSON string array of CSS selectors for elements whose text content should be masked. Example: `'[".user-name", "#email"]'`. || `data-replay-block-class` | `string` | `"rr-block"` | CSS class name for elements to exclude entirely from recording. Elements with this class won't appear in replays. || `data-replay-block-selector` | `string` | `null` | CSS selector for elements to exclude from recording. Example: `".sensitive-content, #private-section"`. |@@ -130,9 +144,8 @@ data-mask-patterns='["re:^/users/\\d+/settings$"]'```html<script- src="https://app.rybbit.io/api/script.js"+ src="https://app.rybbit.io/api/script.js?siteId=456"defer- data-site-id="456"data-skip-patterns='["/admin/**", "/preview/*"]'data-mask-patterns='["/users/*/profile", "/orders/**"]'data-replay-mask-text-selectors='[".user-name", "#email"]'@@ -144,6 +157,8 @@ data-mask-patterns='["re:^/users/\\d+/settings$"]'When session replay is enabled in your site settings, you can fine-tune the recording behavior using the attributes above. This section covers the more complex configuration options.+Each recorded session is capped at 50 MB of replay data. Once a session reaches the cap, the server tells the script to stop recording for the rest of that session. Self-hosted instances can change the cap with the `SESSION_REPLAY_MAX_MB_PER_SESSION` environment variable (`0` turns it off).+### Privacy ControlsProtect sensitive user information using these options:@@ -157,9 +172,8 @@ Protect sensitive user information using these options:**Example - Comprehensive privacy setup:**```html<script- src="https://app.rybbit.io/api/script.js"+ src="https://app.rybbit.io/api/script.js?siteId=123"defer- data-site-id="123"data-replay-block-selector=".admin-panel, #payment-modal"data-replay-ignore-selector="input[name='ssn'], input[name='credit-card']"data-replay-mask-text-selectors='[".user-name", "#email", "[data-pii]"]'@@ -232,9 +246,8 @@ data-replay-slim-dom-options="true"```html<script- src="https://app.rybbit.io/api/script.js"+ src="https://app.rybbit.io/api/script.js?siteId=456"defer- data-site-id="456"data-skip-patterns='["/admin/**", "/preview/*"]'data-mask-patterns='["/users/*/profile", "/orders/**"]'data-debounce="300"diff --git a/docs/content/docs/(docs)/sdks/node.mdx b/docs/content/docs/(docs)/sdks/node.mdxindex 34b366727..aa68ed3e5 100644--- a/docs/content/docs/(docs)/sdks/node.mdx+++ b/docs/content/docs/(docs)/sdks/node.mdx@@ -5,190 +5,136 @@ description: Server-side analytics tracking for Node.js applicationsimport { Callout } from "fumadocs-ui/components/callout";-## Installation+<Callout type="error">+**The published `@rybbit/node` package (1.0.0) doesn't work with the current API.** It sends the API key inside the JSON body, and `/api/track` rejects unknown body fields with a `400`. The package only logs that error when `debug` is on, so events are dropped silently. Until a fixed release ships, call the HTTP API directly with the small helper below.+</Callout>-```bash filename="npm"-npm install @rybbit/node-```+Server-side tracking from Node.js is a `POST` to [`/api/track`](/docs/api/sending-events) with a JSON body. Node 18 and later ship `fetch`, so you don't need a dependency.-```bash filename="yarn"-yarn add @rybbit/node-```+## What you need-## Initialization+- **Your site ID**, from the Rybbit dashboard.+- **An API key** with access to that site, either full-access or restricted to a set that includes `ingest:write`. See [Generating API Keys](/docs/api/getting-started#generating-api-keys). Keep it on the server.+- **The API host**: `https://app.rybbit.io` on Rybbit Cloud, or your own instance URL.-### Syntax+## Helper-```typescript-import { Rybbit } from "@rybbit/node";--const rybbit = new Rybbit(config: RybbitConfig);-```+The examples are ES modules. Set `"type": "module"` in your `package.json`, or name the files `.mjs`.-### Example+```javascript title="rybbit.js"+const RYBBIT_HOST = process.env.RYBBIT_HOST ?? "https://app.rybbit.io";+const RYBBIT_SITE_ID = process.env.RYBBIT_SITE_ID;+const RYBBIT_API_KEY = process.env.RYBBIT_API_KEY;-```javascript-import { Rybbit } from "@rybbit/node";+export async function track(event) {+ const response = await fetch(`${RYBBIT_HOST}/api/track`, {+ method: "POST",+ headers: {+ "Content-Type": "application/json",+ Authorization: `Bearer ${RYBBIT_API_KEY}`,+ },+ body: JSON.stringify({ site_id: RYBBIT_SITE_ID, ...event }),+ });-const rybbit = new Rybbit({- analyticsHost: "https://app.rybbit.io/api",- siteId: "1",- apiKey: "your-secret-api-key",-});+ // Not always JSON: some 200 responses are plain text (see below).+ const body = await response.text();+ if (!response.ok) {+ throw new Error(`Rybbit /api/track ${response.status}: ${body}`);+ }+ return body;+}```-<Callout type="warning">-The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `apiKey`) are missing or invalid.-</Callout>--### Configuration Options--| Option | Type | Default | Description |-| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |-| `analyticsHost` | `string` | - | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |-| `siteId` | `string \| number` | - | **Required.** The Site ID for your website obtained from your Rybbit instance. |-| `apiKey` | `string` | - | **Required.** Your secret API key for the site |-| `debug` | `boolean` | `false` | Enable detailed logging to the console. |+Every event needs a `type`. The server rejects any field it doesn't recognize, so send only the fields listed in [Sending Events](/docs/api/sending-events).-## Tracking Pageviews+## Tracking pageviews-While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.+```javascript+import { track } from "./rybbit.js";-### Syntax+app.get("/products/:id", async (req, res) => {+ const product = await getProduct(req.params.id);-```typescript-await rybbit.pageview(payload?: Payload);+ track({+ type: "pageview",+ hostname: req.hostname,+ pathname: req.path,+ page_title: `Product - ${product.name}`,+ referrer: req.get("referer"),+ // Any stable per-visitor ID. req.session needs session middleware such as express-session.+ anonymous_id: req.session.id,+ ip_address: req.ip,+ user_agent: req.get("user-agent"),+ }).catch(err => console.error(err));++ res.render("product", { product });+});```-### Parameters--- **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.- - `hostname` (`string`): The hostname associated with this pageview.- - `pathname` (`string`): The path of the page/resource being viewed.- - `querystring` (`string`): Any query parameters associated with the path.- - `screenWidth` (`number`): Screen width in pixels.- - `screenHeight` (`number`): Screen height in pixels.- - `language` (`string`): Language code.- - `page_title` (`string`): The title of the page or resource.- - `referrer` (`string`): The referrer URL.- - `user_id` (`string`): A unique identifier for the user.- - `user_agent` (`string`): The user agent string of the client.- - `ip_address` (`string`): The IP address of the client.--<Callout type="info">-The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.-</Callout>+## Tracking custom events-### Example+Set `type: "custom_event"` and an `event_name`. `properties` is a JSON **string** of at most 2048 characters.```javascript-// Track a server-rendered page view-async function handleProductPageRequest(req, res) {- // ... server logic to render product page ...+await track({+ type: "custom_event",+ event_name: "user_registered",+ pathname: "/register",+ user_id: newUser.id,+ anonymous_id: req.session.id,+ ip_address: req.ip,+ user_agent: req.get("user-agent"),+ properties: JSON.stringify({ method: "email" }),+});+```- await rybbit.pageview({- hostname: req.hostname,- pathname: `/products/${req.params.productId}`,- page_title: `Product - ${product.name}`,- ip_address: req.ip- });+## Keeping visitors apart- // ... send response ...-}+Without extra fields, Rybbit derives the visitor from the request's IP address and user agent, which are your server's. Every event would then belong to one visitor. Give each event one of these:-// Track an API resource view-async function serveApiResource(req) {- await rybbit.pageview({- hostname: "api.myservice.com",- pathname: `/v1/items/${req.params.itemId}`,- user_id: req.user.id,- ip_address: req.ip- });- // ... return API data ...-}-```+- **`anonymous_id`**: any stable string per visitor, such as a session ID. Rybbit derives the visitor from it instead of IP and user agent. Up to 255 characters.+- **`ip_address` and `user_agent`**: the visitor's, read from the incoming request. Rybbit uses them for the visitor ID, geolocation and device detection.-## Tracking Custom Events+Add `user_id` for signed-in users.-Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.+`ip_address` and `user_agent` are used only when the request carries an `Authorization: Bearer` key that has access to the site and is full-access or holds `ingest:write`. Without such a key, including a key sent as `?api_key=`, they're ignored and the event is treated as a browser hit from your server. `ip_address` must be a valid IPv4 or IPv6 address. If your app runs behind a proxy, configure it so `req.ip` is the visitor's address (in Express, the `trust proxy` setting).-### Syntax+<Callout type="warn">+Bot detection still classifies the user agent. Node's default `User-Agent` (`node`) and simple product strings like `MyApp/1.0` are classified as bots, so pass the visitor's real user agent. With bot blocking on (the default), bot events are stored as bot traffic and don't appear in your analytics, yet the response is still `200`.+</Callout>-```typescript-await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);-```+## Responses-### Parameters--- **`eventName`** (`string`, Required): The name of the event you want to track.-- **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.- - `hostname` (`string`): The hostname associated with this event.- - `pathname` (`string`): The path or resource context for this event.- - `querystring` (`string`): Any query parameters relevant to the event's context.- - `screenWidth` (`number`): Screen width in pixels.- - `screenHeight` (`number`): Screen height in pixels.- - `language` (`string`): Language code.- - `page_title` (`string`): The title of the page or resource context.- - `referrer` (`string`): The referrer URL.- - `user_id` (`string`): A unique identifier for the user.- - `user_agent` (`string`): The user agent string of the client.- - `ip_address` (`string`): The IP address of the client.-- **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values can be a `string`, `number`, `boolean`, or an array of these types.--<Callout type="info">-The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).-</Callout>+- `200` with `{"success":true}`: accepted. A detected bot also gets this response.+- `200` with `{"success":true,"message":"..."}`: matched a site exclusion and was not stored.+- `200` with a plain-text body: the site is over its monthly event limit or its organization has no plan; nothing was stored.+- `400`: invalid payload, with details of the failing fields.+- `404`: unknown site ID.-### Example+On Rybbit Cloud each request with a Bearer key counts against the key owner's API rate limits (see [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only)). When the limit is used up, `/api/track` doesn't return `429`. It stops honoring the key, so `ip_address` and `user_agent` are ignored as described above.-```javascript-// Track a new user registration-async function registerUser(userData, req) {- // ... process user registration ...-- await rybbit.event("user_registered",- {- hostname: "auth.myservice.com",- pathname: "/register",- ip_address: req.ip- },- {- userId: newUserId,- registrationMethod: "email"- }- );-}+## Identifying users-// Track a background job completion-async function processDailyReport(reportId) {- // ... generate report ...-- await rybbit.event("report_generated",- {},- {- reportId: reportId,- status: "success",- processingTimeMs: 12345- }- );-}+To attach traits to a user or link a visitor's earlier anonymous events to them, `POST` to `/api/identify`. See [Identifying users](/docs/api/sending-events#identifying-users) for the fields.-// Track an API endpoint usage with specific data-async function handleApiRequest(req) {- // ... handle request ...- await rybbit.event(- "api_v1_item_lookup",- {- hostname: req.hostname,- pathname: req.path,- user_id: req.user.id,- ip_address: req.ip- },- {- itemId: req.params.itemId,- clientVersion: req.headers["x-client-version"]- }- );- // ... return response ...+```javascript+const response = await fetch(`${RYBBIT_HOST}/api/identify`, {+ method: "POST",+ headers: {+ "Content-Type": "application/json",+ Authorization: `Bearer ${RYBBIT_API_KEY}`,+ },+ body: JSON.stringify({+ site_id: RYBBIT_SITE_ID,+ user_id: user.id,+ anonymous_id: req.session.id,+ traits: { email: user.email, name: user.name },+ }),+});++// fetch doesn't throw on 4xx/5xx, so check the status like the track helper does.+const body = await response.text();+if (!response.ok) {+ throw new Error(`Rybbit /api/identify ${response.status}: ${body}`);}-```\ No newline at end of file+```diff --git a/docs/content/docs/(docs)/self-host-vs-cloud.mdx b/docs/content/docs/(docs)/self-host-vs-cloud.mdxindex 2a6533df7..d2868ee9e 100644--- a/docs/content/docs/(docs)/self-host-vs-cloud.mdx+++ b/docs/content/docs/(docs)/self-host-vs-cloud.mdx@@ -26,7 +26,14 @@ Rybbit offers two deployment options: a fully-managed [cloud version](https://ry| **Error tracking** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Organizations/Teams** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> || **Pages View** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Web Vitals** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Check className="w-5 h-5 inline" color="green" strokeWidth={3} /> |+| **Web Vitals** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> || **Email reports** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |-| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <span className="inline-flex items-center gap-1"><Check className="w-5 h-5" color="green" strokeWidth={3}/> (Requires Google OAuth env vars)</span> |+| **Google Search Console integration** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Bots page** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Custom SQL queries and dashboards** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Google and GitHub sign-in** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+| **Emails (invitations, password reset)** | <Check className="w-5 h-5 inline" color="green" strokeWidth={3}/> | <Minus className="w-5 h-5 inline" color="gray" strokeWidth={3} /> |+Self-hosted instances don't send email. To add someone to an organization, an admin creates their account directly with an email and password (**Create User** in organization settings) instead of sending an invitation, and there is no "Forgot password?" link on the login page.++Custom SQL queries are still available to AI assistants on self-hosted instances through the [MCP](/docs/mcp) `run_query` tool.diff --git a/docs/content/docs/(docs)/self-hosting-guides/custom-nginx.mdx b/docs/content/docs/(docs)/self-hosting-guides/custom-nginx.mdxindex ba9d38a55..7872fd4ff 100644--- a/docs/content/docs/(docs)/self-hosting-guides/custom-nginx.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/custom-nginx.mdx@@ -34,9 +34,18 @@ Optionally, include a Mapbox token for globe visualizations:./setup.sh your.domain.name --no-webserver --mapbox-token YOUR_MAPBOX_TOKEN```-This will expose:-- Backend service on port 3001-- Client service on port 3002+This publishes the backend on port 3001 and the client on port 3002 on all interfaces, over plain HTTP.++<Callout type="warn">+Since Nginx runs on the same host, bind both ports to localhost so they can't be reached from outside. Edit these lines in `.env`:++```bash+HOST_BACKEND_PORT="127.0.0.1:3001:3001"+HOST_CLIENT_PORT="127.0.0.1:3002:3002"+```++Then apply the change with `docker compose up -d`. Ports published by Docker bypass host firewalls such as `ufw`, so don't rely on those to block them.+</Callout></Step><Step>@@ -69,8 +78,8 @@ server {add_header X-Content-Type-Options "nosniff" always;add_header X-XSS-Protection "1; mode=block" always;- # Backend service- location ~ ^/(api|\.well-known)/.*$ {+ # Backend service: the API and the OAuth discovery documents MCP clients use+ location ~ ^/(api/|\.well-known/oauth-|\.well-known/openid-configuration) {proxy_pass http://localhost:3001;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;@@ -195,10 +204,10 @@ If you need to use custom ports for Rybbit:./setup.sh your.domain.name --no-webserver --backend-port 8080 --client-port 8081 --mapbox-token YOUR_MAPBOX_TOKEN```-Update your Nginx configuration accordingly:+Bind them to localhost the same way, e.g. `HOST_BACKEND_PORT="127.0.0.1:8080:3001"`, and update your Nginx configuration accordingly:```nginx-location /api/ {+location ~ ^/(api/|\.well-known/oauth-|\.well-known/openid-configuration) {proxy_pass http://localhost:8080; # Custom backend port# ... rest of config}diff --git a/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx b/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdxindex c5f61a73e..c5de91326 100644--- a/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/nginx-proxy-manager.mdx@@ -39,6 +39,8 @@ services:target: /etc/clickhouse-server/config.d/network.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml+ - source: clickhouse_resource_limits+ target: /etc/clickhouse-server/config.d/resource_limits.xml# Profile (user-level) settings are only read from users.d, not config.d- source: clickhouse_user_settingstarget: /etc/clickhouse-server/users.d/user_settings.xml@@ -46,6 +48,9 @@ services:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ # Lets the backend provision the least-privilege `rybbit_query` user+ # (custom SQL queries / dashboards) with SQL at startup.+ - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1healthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]interval: 3s@@ -108,6 +113,7 @@ services:- CLICKHOUSE_HOST=http://rybbit_clickhouse:8123- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ - CLICKHOUSE_QUERY_PASSWORD=${CLICKHOUSE_QUERY_PASSWORD:-${CLICKHOUSE_PASSWORD:-frog}}- POSTGRES_HOST=rybbit_postgres- POSTGRES_PORT=5432- POSTGRES_DB=${POSTGRES_DB:-analytics}@@ -119,7 +125,10 @@ services:- BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}- BASE_URL=${BASE_URL}- DISABLE_SIGNUP=${DISABLE_SIGNUP}+ - DISABLE_TELEMETRY=${DISABLE_TELEMETRY}- MAPBOX_TOKEN=${MAPBOX_TOKEN}+ - CLUSTER_WORKERS=${CLUSTER_WORKERS:-4}+ - DASHBOARD_CACHE_TTL_SECONDS=${DASHBOARD_CACHE_TTL_SECONDS:-30}depends_on:rybbit_clickhouse:condition: service_healthy@@ -174,6 +183,10 @@ configs:</logger><query_thread_log remove="remove"/><query_log remove="remove"/>+ <query_views_log remove="remove"/>+ <query_metric_log remove="remove"/>+ <error_log remove="remove"/>+ <opentelemetry_span_log remove="remove"/><text_log remove="remove"/><trace_log remove="remove"/><metric_log remove="remove"/>@@ -184,18 +197,37 @@ configs:<processors_profile_log remove="remove"/></clickhouse>+ clickhouse_resource_limits:+ content: |+ <clickhouse>+ <!-- Leave headroom for the backend, Redis, Caddy, the kernel, and the+ filesystem cache instead of allowing ClickHouse to exhaust RAM. -->+ <max_server_memory_usage_to_ram_ratio>0.80</max_server_memory_usage_to_ram_ratio>+ <!-- Share at most one query-processing thread per CPU core across all+ concurrent queries. This throttles work rather than rejecting it. -->+ <concurrent_threads_soft_limit_ratio_to_cores>1</concurrent_threads_soft_limit_ratio_to_cores>+ <!-- Bound memory used by background merges and mutations separately. -->+ <merges_mutations_memory_usage_to_ram_ratio>0.25</merges_mutations_memory_usage_to_ram_ratio>+ </clickhouse>+clickhouse_user_settings:content: |<clickhouse><profiles><default><enable_json_type>1</enable_json_type>- <!-- 26.3+ enables async_insert by default; the backend already- batches app-side, so keep inserts synchronous -->- <async_insert>0</async_insert>+ <!-- Combine concurrent inserts into larger blocks inside ClickHouse.+ Wait for the flush so the backend still receives insert errors. -->+ <async_insert>1</async_insert>+ <wait_for_async_insert>1</wait_for_async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>+ <!-- Bound individual queries while preserving enough parallelism+ for large analytics scans. Query-count limits remain unset so+ ingestion is never rejected by admission control. -->+ <max_memory_usage>32000000000</max_memory_usage>+ <max_threads>16</max_threads></default></profiles></clickhouse>@@ -278,11 +310,9 @@ In your Nginx Proxy Manager interface:- Forward Port: `3002`- Enable "Cache Assets", "Block Common Exploits", "Websockets Support"-2. **Add Custom Location**:- - Location: `/api`- - Scheme: `http`- - Forward Hostname/IP: `rybbit_backend`- - Forward Port: `3001`+2. **Add Custom Locations**: add one for each of these locations, all with scheme `http`, Forward Hostname/IP `rybbit_backend`, and Forward Port `3001`:+ - `/api`+ - `/.well-known/oauth-` and `/.well-known/openid-configuration`, which [MCP](/docs/mcp) clients use to discover OAuth login3. **Advanced Configuration** (in the custom location):```nginx@@ -320,7 +350,7 @@ services:# ... existing configlabels:- "traefik.enable=true"- - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"+ - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && (PathPrefix(`/api`) || PathPrefix(`/.well-known/oauth-`) || PathPrefix(`/.well-known/openid-configuration`))"- "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"- "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"- "traefik.docker.network=traefik_proxy"@@ -351,6 +381,9 @@ ingress:- hostname: your.domain.compath: /apiservice: http://rybbit_backend:3001+ - hostname: your.domain.com+ path: ^/\.well-known/(oauth-|openid-configuration)+ service: http://rybbit_backend:3001- hostname: your.domain.comservice: http://rybbit_client:3002- service: http_status:404@@ -403,5 +436,5 @@ docker logs -f nginx-proxy-manager```<Callout type="warning">-Remember to regularly backup your data volumes (`clickhouse-data` and `postgres-data`) and your `.env` file.+Remember to regularly back up your data directories (`clickhouse-data`, `postgres-data`, and `redis-data`) and your `.env` file.</Callout>\ No newline at end of filediff --git a/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx b/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdxindex 88ec81336..61f7f24fe 100644--- a/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/pangolin.mdx@@ -39,22 +39,19 @@ BETTER_AUTH_SECRET=your_generated_secret_here# Required: Disable built-in webserver since Pangolin handles routingUSE_WEBSERVER=false-# ClickHouse configuration+# Database passwords: replace each with your own strong passwordCLICKHOUSE_DB=analytics-CLICKHOUSE_USER=default-CLICKHOUSE_PASSWORD=changeme+CLICKHOUSE_PASSWORD=your_clickhouse_password-# PostgreSQL configurationPOSTGRES_DB=analytics-POSTGRES_USER=changeme-POSTGRES_PASSWORD=changeme+POSTGRES_USER=rybbit+POSTGRES_PASSWORD=your_postgres_password-# Redis configuration-REDIS_PASSWORD=changeme+REDIS_PASSWORD=your_redis_password-# Ports in host:container format (Pangolin needs it like this)-HOST_BACKEND_PORT=3001:3001-HOST_CLIENT_PORT=3002:3002+# Host port mappings in host_ip:host_port:container_port format+HOST_BACKEND_PORT=127.0.0.1:3001:3001+HOST_CLIENT_PORT=127.0.0.1:3002:3002# Optional: Disable new user signups after creating admin account# DISABLE_SIGNUP=true@@ -63,8 +60,10 @@ HOST_CLIENT_PORT=3002:3002# MAPBOX_TOKEN=your_mapbox_token```+Set the passwords before the first start: Postgres only reads `POSTGRES_USER` and `POSTGRES_PASSWORD` when it creates its data volume. If you reuse an existing `postgres-data` volume, keep the user and password it was created with.+<Callout type="info">-The `HOST_BACKEND_PORT` and `HOST_CLIENT_PORT` values use the `host:container` format without binding to `127.0.0.1`. This is intentional β the Newt container inside the Docker network handles routing, so the ports do not need to be exposed to your host. Even if you already run services on ports 3001/3002 on your host, there will be no conflict.+Newt reaches the backend and client over the Docker network, so the host port mappings are only for access from the server itself. Binding them to `127.0.0.1` keeps them off the network. If ports 3001 or 3002 are already taken on your host, change the host port, e.g. `127.0.0.1:4001:3001`. A value without an IP, such as `3001:3001`, publishes the port on all interfaces.</Callout></Step>@@ -94,6 +93,8 @@ services:target: /etc/clickhouse-server/config.d/network.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml+ - source: clickhouse_resource_limits+ target: /etc/clickhouse-server/config.d/resource_limits.xml# Profile (user-level) settings are only read from users.d, not config.d- source: clickhouse_user_settingstarget: /etc/clickhouse-server/users.d/user_settings.xml@@ -101,6 +102,9 @@ services:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ # Lets the backend provision the least-privilege `rybbit_query` user+ # (custom SQL queries / dashboards) with SQL at startup.+ - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1healthcheck:test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]interval: 3s@@ -109,7 +113,8 @@ services:start_period: 10srestart: unless-stoppedports:- - "8123:8123"+ # Localhost-only: reach from outside via SSH tunnel+ - "127.0.0.1:8123:8123"postgres:image: postgres:17.4@@ -128,11 +133,15 @@ services:start_period: 10srestart: unless-stoppedports:- - "5432:5432"+ # Localhost-only: reach from outside via SSH tunnel+ - "127.0.0.1:5432:5432"redis:image: redis:8.6.4-alpinecontainer_name: redis+ ports:+ # Localhost-only: reach from outside via SSH tunnel+ - "127.0.0.1:6379:6379"volumes:- redis-data:/datahealthcheck:@@ -163,6 +172,7 @@ services:- CLICKHOUSE_HOST=http://clickhouse:8123- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ - CLICKHOUSE_QUERY_PASSWORD=${CLICKHOUSE_QUERY_PASSWORD:-${CLICKHOUSE_PASSWORD:-frog}}- POSTGRES_HOST=postgres- POSTGRES_PORT=5432- POSTGRES_DB=${POSTGRES_DB:-analytics}@@ -176,6 +186,8 @@ services:- DISABLE_SIGNUP=${DISABLE_SIGNUP}- DISABLE_TELEMETRY=${DISABLE_TELEMETRY}- MAPBOX_TOKEN=${MAPBOX_TOKEN}+ - CLUSTER_WORKERS=${CLUSTER_WORKERS:-4}+ - DASHBOARD_CACHE_TTL_SECONDS=${DASHBOARD_CACHE_TTL_SECONDS:-30}depends_on:clickhouse:condition: service_healthy@@ -225,6 +237,10 @@ configs:</logger><query_thread_log remove="remove"/><query_log remove="remove"/>+ <query_views_log remove="remove"/>+ <query_metric_log remove="remove"/>+ <error_log remove="remove"/>+ <opentelemetry_span_log remove="remove"/><text_log remove="remove"/><trace_log remove="remove"/><metric_log remove="remove"/>@@ -235,18 +251,37 @@ configs:<processors_profile_log remove="remove"/></clickhouse>+ clickhouse_resource_limits:+ content: |+ <clickhouse>+ <!-- Leave headroom for the backend, Redis, Caddy, the kernel, and the+ filesystem cache instead of allowing ClickHouse to exhaust RAM. -->+ <max_server_memory_usage_to_ram_ratio>0.80</max_server_memory_usage_to_ram_ratio>+ <!-- Share at most one query-processing thread per CPU core across all+ concurrent queries. This throttles work rather than rejecting it. -->+ <concurrent_threads_soft_limit_ratio_to_cores>1</concurrent_threads_soft_limit_ratio_to_cores>+ <!-- Bound memory used by background merges and mutations separately. -->+ <merges_mutations_memory_usage_to_ram_ratio>0.25</merges_mutations_memory_usage_to_ram_ratio>+ </clickhouse>+clickhouse_user_settings:content: |<clickhouse><profiles><default><enable_json_type>1</enable_json_type>- <!-- 26.3+ enables async_insert by default; the backend already- batches app-side, so keep inserts synchronous -->- <async_insert>0</async_insert>+ <!-- Combine concurrent inserts into larger blocks inside ClickHouse.+ Wait for the flush so the backend still receives insert errors. -->+ <async_insert>1</async_insert>+ <wait_for_async_insert>1</wait_for_async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>+ <!-- Bound individual queries while preserving enough parallelism+ for large analytics scans. Query-count limits remain unset so+ ingestion is never rejected by admission control. -->+ <max_memory_usage>32000000000</max_memory_usage>+ <max_threads>16</max_threads></default></profiles></clickhouse>@@ -292,6 +327,8 @@ In your Pangolin dashboard, create a new site for your Rybbit domain and configu- Target: `backend` (the Docker container hostname)- Port: `3001`+ Route paths starting with `/.well-known/oauth-` and `/.well-known/openid-configuration` to the same backend target. [MCP](/docs/mcp) clients use them to discover OAuth login.+For both resources, add these custom headers in the Pangolin configuration:| Header | Value |@@ -360,7 +397,7 @@ docker compose psVerify your Newt credentials and Pangolin endpoint:```bash-docker compose logs -f newt-rybbit+docker compose logs -f newt```Make sure `PANGOLIN_ENDPOINT`, `NEWT_ID`, and `NEWT_SECRET` are correct in your `docker-compose.yml`.diff --git a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdxindex 7f2e21629..9152e6329 100644--- a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-advanced.mdx@@ -49,8 +49,19 @@ If you prefer to use your own web server instead of the built-in Caddy server, yThis will:- Not start the Caddy container-- Expose the backend service on host port 3001 (or your custom port)-- Expose the client service on host port 3002 (or your custom port)+- Expose the backend service on host port 3001 (or your custom port) on all interfaces+- Expose the client service on host port 3002 (or your custom port) on all interfaces++<Callout type="warn">+Both ports serve plain HTTP. If your web server runs on the same host, bind them to localhost by editing these lines in `.env`, then run `docker compose up -d`. If you set custom ports, keep your host port, e.g. `127.0.0.1:8080:3001`:++```bash+HOST_BACKEND_PORT="127.0.0.1:3001:3001"+HOST_CLIENT_PORT="127.0.0.1:3002:3002"+```++If your web server runs elsewhere, restrict the ports with your hosting provider's firewall. Ports published by Docker bypass host firewalls such as `ufw`.+</Callout><Callout type="info">For detailed configuration examples with Nginx, Traefik, NPM, and other reverse proxies, see our [Manual Docker Compose Setup](/docs/self-hosting-guides/self-hosting-manual) guide.@@ -79,20 +90,64 @@ POSTGRES_USER=frogPOSTGRES_PASSWORD=frogPOSTGRES_DB=analyticsCLICKHOUSE_DB=analytics+REDIS_PASSWORD=changeme-# Custom image tags+# Image tag to run: latest, a release like v2.9.2, edge, or sha-<commit>IMAGE_TAG=latest# Port mapping (only needed for custom ports or --no-webserver)-HOST_BACKEND_PORT="3001:3001"-HOST_CLIENT_PORT="3002:3002"+HOST_BACKEND_PORT="127.0.0.1:3001:3001"+HOST_CLIENT_PORT="127.0.0.1:3002:3002"+```++`setup.sh` doesn't generate database or Redis passwords, so the defaults above apply until you set your own. Set them before the first start: Postgres only reads `POSTGRES_USER` and `POSTGRES_PASSWORD` when it creates its data volume. See [Image tags](/docs/managing-your-installation#image-tags) for what each `IMAGE_TAG` value points to.++`docker-compose.yml` also passes these to the backend:++| Variable | Default | What it does |+| --- | --- | --- |+| `CLUSTER_WORKERS` | `4` | Number of backend worker processes. `0` runs a single process. |+| `DASHBOARD_CACHE_TTL_SECONDS` | `30` | How long dashboard query results are cached in Redis, in seconds. The maximum is 30; `0` disables the cache. Not in 2.9.2; applies to `edge` images and the next release. |+| `CLICKHOUSE_QUERY_PASSWORD` | `CLICKHOUSE_PASSWORD` | Password for the read-only `rybbit_query` ClickHouse user the backend creates for custom SQL queries, such as the MCP `run_query` tool. |+| `DISABLE_TELEMETRY` | unset | Set to `true` to turn off [anonymous usage telemetry](/docs/managing-your-installation#anonymous-usage-telemetry). |+| `OPENROUTER_API_KEY`, `OPENROUTER_MODEL` | unset | An [OpenRouter](https://openrouter.ai) key and model for generating custom SQL queries from plain-language questions. |+| `LITE_DASHBOARD` | unset | For very high-traffic installs. Set to `true` and the backend keeps hourly rollup tables and serves the site list from them. The rollups only see new events: on an install that already has data, run `docker compose run --rm --no-deps backend node dist/scripts/backfillLiteDashboardMVs.js --cutoff "<YYYY-MM-DD HH:MM:SS>"` once, with the cutoff at the moment you enabled it. |+| `DEPLOYMENT` | unset | Shows the Query and Dashboards pages and the admin panel in the client. |++`LITE_DASHBOARD` and `DEPLOYMENT` are compiled into the client when its image is built. The prebuilt images are built without them, so with prebuilt images `LITE_DASHBOARD` only changes the backend and `DEPLOYMENT` does nothing. To use them fully, build the images yourself with `docker compose build` after setting them in `.env`.++### Variables that aren't in docker-compose.yml++The backend's `environment` list in `docker-compose.yml` is explicit, so a variable you add to `.env` only reaches the backend if that list mentions it. To set anything else, add it in a `docker-compose.override.yml` file next to `docker-compose.yml`. Docker Compose loads it automatically and merges its `environment` entries with the main file:++```yaml+services:+ backend:+ environment:+ - LOG_LEVEL=warn+ - SESSION_REPLAY_MAX_MB_PER_SESSION=100```+Then run your usual start command (for example `docker compose --profile with-webserver up -d`) to recreate the backend. Variables you might set this way:++| Variable | Default | What it does |+| --- | --- | --- |+| `SESSION_REPLAY_MAX_MB_PER_SESSION` | `50` | Stops storing replay data for a session once it reaches this many MB. `0` removes the cap. Not in 2.9.2; applies to `edge` images and the next release. |+| `LOG_LEVEL` | `info` | Backend log level, such as `debug`, `info`, `warn`, or `error`. |+| `DISABLE_STICKY_IDENTITY` | unset | Set to `true` to stop keeping a visitor's ID stable when their IP address rotates during a visit. |+| `DISABLE_REDIS_ANOMALY` | unset | Set to `true` to keep bot-detection rate counters in each process instead of Redis. |++`update.sh` leaves `docker-compose.override.yml` in place, while it stashes edits made directly to `docker-compose.yml`.+## ClickHouse Timezone+<Callout type="info">+This section applies to the first release after 2.9.2 and to `edge` images. The current `latest` images (2.9.2) don't include the UTC change yet.+</Callout>+Rybbit stores every timestamp as a UTC instant and converts to your dashboard timezone when it queries. Every time column is declared `DateTime('UTC')`, and the backend writes timestamps with an explicit UTC offset, so the ClickHouse server's own `<timezone>` setting does not change what gets stored. Leave it at the default (UTC) unless you have a reason not to; the backend logs a warning at startup if it is anything else.-### Upgrading from 2.9.1 or earlier on a non-UTC ClickHouse+### Upgrading from 2.9.2 or earlier on a non-UTC ClickHouseBefore this change the backend wrote timezone-less strings, which ClickHouse read in the server's timezone. If your ClickHouse was configured for anything but UTC, two things need attention after upgrading:@@ -111,7 +166,7 @@ Before this change the backend wrote timezone-less strings, which ClickHouse reaRepeat for `bot_events` and `bot_observations` (partitioned on `timestamp`), and `session_replay_events` (`timestamp`), `session_replay_metadata` and `session_replay_metadata_v2` (`start_time`). With `LITE_DASHBOARD=true`, do the same for `sessions_mv_target` (`start_time`) and the `*_hourly_mv_target` tables (`event_hour`); `session_hourly_mv_target` is rebuilt by its view every hour and can be skipped. On `ReplacingMergeTree` and `AggregatingMergeTree` tables compare `count()` with `FINAL`, since background merges can change the raw count. Materialized views stay attached to the swapped-in table. The copy rewrites every row, so run it off-peak. Step 2's copy also re-partitions every row it writes, so a table you fix there can skip this step. Start the backend when you are done, unless you continue with step 2.-2. **Shifted timestamps.** Keep the backend stopped for this step too: any event that arrives between the copy and the swap ends up only in the table you drop. Rows written by rybbit-backend 2.9.0 or 2.9.1 while ClickHouse was not in UTC were stored shifted by the server's offset (the dashboard looked frozen at the upgrade time). Rows written by 2.8.0 or earlier were shifted only if the backend container's `TZ` differed from the ClickHouse timezone. Rybbit cannot correct these automatically: a shifted row and a correct row can carry the same timestamp, so only you know which rows the old backend wrote. If you want them fixed, use the same copy-and-swap on the `events` table with your own bounds, then rebuild the rollups from it:+2. **Shifted timestamps.** Keep the backend stopped for this step too: any event that arrives between the copy and the swap ends up only in the table you drop. Rows written by rybbit-backend 2.9.0, 2.9.1, or 2.9.2 while ClickHouse was not in UTC were stored shifted by the server's offset (the dashboard looked frozen at the upgrade time). Rows written by 2.8.0 or earlier were shifted only if the backend container's `TZ` differed from the ClickHouse timezone. Rybbit cannot correct these automatically: a shifted row and a correct row can carry the same timestamp, so only you know which rows the old backend wrote. If you want them fixed, use the same copy-and-swap on the `events` table with your own bounds, then rebuild the rollups from it:```sqlCREATE TABLE events_fixed AS events;diff --git a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdxindex d71581575..20b64dc0d 100644--- a/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx+++ b/docs/content/docs/(docs)/self-hosting-guides/self-hosting-manual.mdx@@ -47,18 +47,21 @@ DISABLE_SIGNUP=false# Optional but recommended: Mapbox token for globe visualizationsMAPBOX_TOKEN=your_mapbox_token-# Optional: Custom ports (only needed if you want different ports)-# HOST_BACKEND_PORT="3001:3001"-# HOST_CLIENT_PORT="3002:3002"+# Optional: Custom host ports (defaults bind to localhost only)+# HOST_BACKEND_PORT="127.0.0.1:3001:3001"+# HOST_CLIENT_PORT="127.0.0.1:3002:3002"-# Optional: Database credentials (defaults work fine)+# Optional: Database credentials (defaults work, but change them for production)# CLICKHOUSE_PASSWORD=frog# POSTGRES_USER=frog# POSTGRES_PASSWORD=frog# POSTGRES_DB=analytics# CLICKHOUSE_DB=analytics+# REDIS_PASSWORD=changeme```+For the other settings Docker Compose reads, see [Environment variables](/docs/self-hosting-guides/self-hosting-advanced#environment-variables).+<Callout type="info">To generate a secure `BETTER_AUTH_SECRET`, you can use:```bash@@ -72,10 +75,10 @@ openssl rand -hex 32<Tabs items={['Built-in Caddy (Automatic SSL)', 'Without Caddy']}><Tab value="Built-in Caddy (Automatic SSL)">-If you don't have a reverse proxy and want automatic SSL certificates, use the default docker-compose.yml:+If you don't have a reverse proxy and want automatic SSL certificates, start the stack with the `with-webserver` profile, which adds the Caddy service:```bash-docker compose up -d+docker compose --profile with-webserver up -d```This will:@@ -84,36 +87,36 @@ This will:- Make your app available at `https://your.domain.com`</Tab><Tab value="Without Caddy">-If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), you need to exclude Caddy and expose the ports:+If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), start the stack without the `with-webserver` profile. Caddy only runs when that profile is enabled:-1. **Option B1: Modify the .env file**- ```bash- # Add these lines to expose ports- HOST_BACKEND_PORT="3001:3001"- HOST_CLIENT_PORT="3002:3002"- ```+```bash+docker compose up -d+```- Then start without Caddy:- ```bash- docker compose up -d backend client clickhouse postgres- ```+By default the backend and client are published on `127.0.0.1:3001` and `127.0.0.1:3002`, so a reverse proxy running on the same host can reach them and nothing else can. You don't need to change any ports for that setup.-2. **Option B2: Use docker-compose.override.yml**- Create a `docker-compose.override.yml` file:- ```yaml- services:- backend:- ports:- - "3001:3001"- client:- ports:- - "3002:3002"- ```+If your proxy runs on another machine, publish the ports on all interfaces in `.env`:- Then start without Caddy:- ```bash- docker compose up -d backend client clickhouse postgres- ```+```bash+HOST_BACKEND_PORT="3001:3001"+HOST_CLIENT_PORT="3002:3002"+```++<Callout type="warn">+This exposes the backend and client over plain HTTP to anyone who can reach the server. Restrict access with a firewall at your hosting provider. Ports published by Docker bypass host firewalls such as `ufw`.+</Callout>++To change ports with a `docker-compose.override.yml` file instead, use the `!override` tag, which needs Docker Compose 2.24.4 or later. Without it, Docker Compose adds your ports to the default `127.0.0.1` ones instead of replacing them:++```yaml+services:+ backend:+ ports: !override+ - "127.0.0.1:8080:3001"+ client:+ ports: !override+ - "127.0.0.1:8081:3002"+```</Tab></Tabs></Step>@@ -123,6 +126,7 @@ If you have your own reverse proxy (Nginx, Traefik, Coolify, etc.), you need toIf you're using your own reverse proxy, configure it to:- Proxy requests to `/api/*` to `http://localhost:3001`+- Proxy requests to `/.well-known/oauth-*` and `/.well-known/openid-configuration*` to `http://localhost:3001`. [MCP](/docs/mcp) clients use these to discover OAuth login.- Proxy all other requests to `http://localhost:3002`Example configurations:@@ -150,6 +154,15 @@ server {proxy_set_header X-Forwarded-Proto $scheme;}+ # OAuth discovery for MCP clients+ location ~ ^/\.well-known/(oauth-|openid-configuration) {+ proxy_pass http://localhost:3001;+ proxy_set_header Host $host;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header X-Forwarded-Proto $scheme;+ }+location / {proxy_pass http://localhost:3002;proxy_set_header Host $host;@@ -166,7 +179,7 @@ services:backend:labels:- "traefik.enable=true"- - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && PathPrefix(`/api`)"+ - "traefik.http.routers.rybbit-api.rule=Host(`your.domain.com`) && (PathPrefix(`/api`) || PathPrefix(`/.well-known/oauth-`) || PathPrefix(`/.well-known/openid-configuration`))"- "traefik.http.routers.rybbit-api.tls.certresolver=letsencrypt"- "traefik.http.services.rybbit-api.loadbalancer.server.port=3001"@@ -185,11 +198,11 @@ services:### Start the Services```bash-# Start all services-docker compose up -d+# With the built-in Caddy webserver+docker compose --profile with-webserver up -d-# Or start specific services (without Caddy)-docker compose up -d backend client clickhouse postgres+# Without Caddy (your own reverse proxy)+docker compose up -d```</Step>@@ -222,7 +235,7 @@ Rybbit consists of these services:- **backend**: Node.js API server (port 3001)- **postgres**: User data and configuration- **clickhouse**: Analytics data storage-- **redis**: Session tracking and background job queues+- **redis**: Shared state for session tracking, visitor identity, bot detection counters, rate limits, the dashboard cache, and session replay and import budgets- **caddy**: Reverse proxy with automatic SSL (optional)## Common Configurations@@ -258,6 +271,8 @@ services:target: /etc/clickhouse-server/config.d/network.xml- source: clickhouse_loggingtarget: /etc/clickhouse-server/config.d/logging_rules.xml+ - source: clickhouse_resource_limits+ target: /etc/clickhouse-server/config.d/resource_limits.xml# Profile (user-level) settings are only read from users.d, not config.d- source: clickhouse_user_settingstarget: /etc/clickhouse-server/users.d/user_settings.xml@@ -265,16 +280,11 @@ services:- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ # Lets the backend provision the least-privilege `rybbit_query` user+ # (custom SQL queries / dashboards) with SQL at startup.+ - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1healthcheck:- test:- [- "CMD",- "wget",- "--no-verbose",- "--tries=1",- "--spider",- "http://localhost:8123/ping",- ]+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8123/ping"]interval: 3stimeout: 5sretries: 5@@ -335,6 +345,7 @@ services:- CLICKHOUSE_HOST=http://clickhouse:8123- CLICKHOUSE_DB=${CLICKHOUSE_DB:-analytics}- CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-frog}+ - CLICKHOUSE_QUERY_PASSWORD=${CLICKHOUSE_QUERY_PASSWORD:-${CLICKHOUSE_PASSWORD:-frog}}- POSTGRES_HOST=postgres- POSTGRES_PORT=5432- POSTGRES_DB=${POSTGRES_DB:-analytics}@@ -349,6 +360,8 @@ services:- DISABLE_SIGNUP=${DISABLE_SIGNUP}- DISABLE_TELEMETRY=${DISABLE_TELEMETRY}- MAPBOX_TOKEN=${MAPBOX_TOKEN}+ - CLUSTER_WORKERS=${CLUSTER_WORKERS:-4}+ - DASHBOARD_CACHE_TTL_SECONDS=${DASHBOARD_CACHE_TTL_SECONDS:-30}depends_on:clickhouse:condition: service_healthy@@ -357,15 +370,7 @@ services:redis:condition: service_healthyhealthcheck:- test:- [- "CMD",- "wget",- "--no-verbose",- "--tries=1",- "--spider",- "http://127.0.0.1:3001/api/health",- ]+ test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3001/api/health"]interval: 3stimeout: 5sretries: 5@@ -376,7 +381,7 @@ services:- traefik.docker.network=coolify- traefik.http.routers.rybbit-backend.entrypoints=https- traefik.http.routers.rybbit-backend.tls=true- - traefik.http.routers.rybbit-backend.rule=Host(`${DOMAIN_NAME}`) && (Path(`/api`) || PathPrefix(`/api/`))+ - traefik.http.routers.rybbit-backend.rule=Host(`${DOMAIN_NAME}`) && (Path(`/api`) || PathPrefix(`/api/`) || PathPrefix(`/.well-known/oauth-`) || PathPrefix(`/.well-known/openid-configuration`))- traefik.http.services.rybbit-backend.loadbalancer.server.port=3001- traefik.http.routers.rybbit-backend.priority=100- traefik.http.middlewares.rybbit-forward-headers.headers.customrequestheaders.X-Forwarded-Proto=https@@ -424,6 +429,10 @@ configs:</logger><query_thread_log remove="remove"/><query_log remove="remove"/>+ <query_views_log remove="remove"/>+ <query_metric_log remove="remove"/>+ <error_log remove="remove"/>+ <opentelemetry_span_log remove="remove"/><text_log remove="remove"/><trace_log remove="remove"/><metric_log remove="remove"/>@@ -434,18 +443,37 @@ configs:<processors_profile_log remove="remove"/></clickhouse>+ clickhouse_resource_limits:+ content: |+ <clickhouse>+ <!-- Leave headroom for the backend, Redis, Caddy, the kernel, and the+ filesystem cache instead of allowing ClickHouse to exhaust RAM. -->+ <max_server_memory_usage_to_ram_ratio>0.80</max_server_memory_usage_to_ram_ratio>+ <!-- Share at most one query-processing thread per CPU core across all+ concurrent queries. This throttles work rather than rejecting it. -->+ <concurrent_threads_soft_limit_ratio_to_cores>1</concurrent_threads_soft_limit_ratio_to_cores>+ <!-- Bound memory used by background merges and mutations separately. -->+ <merges_mutations_memory_usage_to_ram_ratio>0.25</merges_mutations_memory_usage_to_ram_ratio>+ </clickhouse>+clickhouse_user_settings:content: |<clickhouse><profiles><default><enable_json_type>1</enable_json_type>- <!-- 26.3+ enables async_insert by default; the backend already- batches app-side, so keep inserts synchronous -->- <async_insert>0</async_insert>+ <!-- Combine concurrent inserts into larger blocks inside ClickHouse.+ Wait for the flush so the backend still receives insert errors. -->+ <async_insert>1</async_insert>+ <wait_for_async_insert>1</wait_for_async_insert><log_queries>0</log_queries><log_query_threads>0</log_query_threads><log_processors_profiles>0</log_processors_profiles>+ <!-- Bound individual queries while preserving enough parallelism+ for large analytics scans. Query-count limits remain unset so+ ingestion is never rejected by admission control. -->+ <max_memory_usage>32000000000</max_memory_usage>+ <max_threads>16</max_threads></default></profiles></clickhouse>@@ -462,20 +490,23 @@ Note: you don't need to add a domain for `backend` service in Coolify since clie### Using with Nginx Proxy Manager-1. Set up port exposure in your .env:+The [Nginx Proxy Manager guide](/docs/self-hosting-guides/nginx-proxy-manager) connects NPM to Rybbit over a Docker network, so no ports are published. If you'd rather point NPM at host ports:++1. Set up port exposure in your .env (see the warning under [Without Caddy](#choose-your-setup-method) about publishing on all interfaces):```bashHOST_BACKEND_PORT="3001:3001"HOST_CLIENT_PORT="3002:3002"```2. Create a proxy host pointing to your server IP:3002-3. Add a custom location `/api/*` pointing to your server IP:3001+3. Add custom locations `/api`, `/.well-known/oauth-`, and `/.well-known/openid-configuration` pointing to your server IP:3001### Database PersistenceData is automatically persisted in Docker volumes:- `rybbit_clickhouse-data`: Analytics data- `rybbit_postgres-data`: User accounts and site configurations+- `rybbit_redis-data`: Active sessions and other short-lived state## Advanced Configurations@@ -509,7 +540,7 @@ Ensure the database services are healthy:docker compose ps```-Both postgres and clickhouse should show "healthy" status.+The clickhouse, postgres, and redis services should show "healthy" status. The backend waits for ClickHouse and Redis to be healthy before it starts.<Callout type="info">For more advanced configurations and setup script options, see our [Advanced Self-Hosting Guide](/docs/self-hosting-guides/self-hosting-advanced).diff --git a/docs/content/docs/(docs)/self-hosting.mdx b/docs/content/docs/(docs)/self-hosting.mdxindex af6dbc8e0..ec4c71689 100644--- a/docs/content/docs/(docs)/self-hosting.mdx+++ b/docs/content/docs/(docs)/self-hosting.mdx@@ -87,7 +87,7 @@ If you want to enable 3D map visualizations, you can add the `--mapbox-token` fl```-The script will create a `.env` file and then build and start the containers. This might take a few minutes the first time.+The script creates a `.env` file, then pulls the prebuilt images and starts the containers, including Caddy (`docker compose --profile with-webserver up -d`). This might take a few minutes the first time.<Callout type="info">By default, we assume you are on a blank VPS and automatically setup a Caddy webserver. If you want to use your own webserver or need more control over the setup, check out:diff --git a/docs/content/docs/(docs)/tagging.mdx b/docs/content/docs/(docs)/tagging.mdxindex 8940dd032..88b0a3ef7 100644--- a/docs/content/docs/(docs)/tagging.mdx+++ b/docs/content/docs/(docs)/tagging.mdx@@ -13,14 +13,15 @@ Add a `data-tag` attribute to your Rybbit script tag. Every event (pageviews, cu```html<script- src="https://app.rybbit.io/api/script.js"- async- data-site-id="YOUR_SITE_ID"+ src="https://app.rybbit.io/api/script.js?siteId=YOUR_SITE_ID"+ deferdata-tag="variant-a"></script>```-The tag is a simple string with a maximum length of 256 characters. If `data-tag` is not set or is empty, no tag is stored.+The tag is a simple string of at most 256 characters. The script doesn't shorten it: a longer tag makes the server reject every event from the page with `400`, so nothing is tracked. If `data-tag` is not set or is empty, no tag is stored.++Older snippets that pass the site ID as `data-site-id` instead of `?siteId=` still work.## Use Cases@@ -30,10 +31,10 @@ Serve different script tags to different user groups and compare behavior:```html<!-- Variant A -->-<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-a"></script>+<script src="https://app.rybbit.io/api/script.js?siteId=1" data-tag="homepage-v2-a" defer></script><!-- Variant B -->-<script src="https://app.rybbit.io/api/script.js" async data-site-id="1" data-tag="homepage-v2-b"></script>+<script src="https://app.rybbit.io/api/script.js?siteId=1" data-tag="homepage-v2-b" defer></script>```Then filter by tag in the dashboard to compare metrics between variants.@@ -44,9 +45,8 @@ Tag events with the current deploy version to correlate releases with changes in```html<script- src="https://app.rybbit.io/api/script.js"- async- data-site-id="1"+ src="https://app.rybbit.io/api/script.js?siteId=1"+ deferdata-tag="v2.4.1"></script>```@@ -57,9 +57,8 @@ Label traffic from different sources, campaigns, or user segments:```html<script- src="https://app.rybbit.io/api/script.js"- async- data-site-id="1"+ src="https://app.rybbit.io/api/script.js?siteId=1"+ deferdata-tag="beta-users"></script>```diff --git a/docs/content/docs/(docs)/troubleshooting.mdx b/docs/content/docs/(docs)/troubleshooting.mdxindex 2dd5bc5db..244b35437 100644--- a/docs/content/docs/(docs)/troubleshooting.mdx+++ b/docs/content/docs/(docs)/troubleshooting.mdx@@ -65,33 +65,40 @@ docker network rm $(docker network ls | grep -v "bridge\|host\|none" | awk '{priIf you only want to clean up Rybbit-related Docker resources without affecting other containers, use these commands instead:+Run these from the Rybbit directory. Add `--profile with-webserver` so the Caddy container is included.+```bash# Stop and remove Rybbit containers-docker-compose down+docker compose --profile with-webserver down-# Remove Rybbit images-docker-compose down --rmi all+# Also remove Rybbit images+docker compose --profile with-webserver down --rmi all-# Remove Rybbit volumes (this will delete your data!)-docker-compose down --volumes+# Also remove Rybbit volumes (this will delete your data!)+docker compose --profile with-webserver down --volumes# Complete Rybbit cleanup-docker-compose down --rmi all --volumes --remove-orphans+docker compose --profile with-webserver down --rmi all --volumes --remove-orphans```### After Cleanup-Once you've completed the cleanup, you can restart Rybbit by following the setup instructions:+Once you've completed the cleanup, set Rybbit up again by running the setup script, which creates a new `.env` file and starts the services:```bash-# Copy environment file-cp .env.example .env+./setup.sh your.domain.name+```++If you'd rather write `.env` yourself, copy `.env.example`, set `DOMAIN_NAME` and `BETTER_AUTH_SECRET` (generate it with `openssl rand -hex 32`), then start the services:-# Edit .env with your configuration-# Then start the services-docker-compose up -d+```bash+cp .env.example .env+# Edit .env, then start everything including the Caddy webserver:+docker compose --profile with-webserver up -d```+Leave out `--profile with-webserver` if you run your own reverse proxy.+## ClickHouse keeps crashing on a Proxmox VMClickHouse requires the SSE 4.2 instruction set. Proxmox VMs default to a generic CPU type (like `kvm64` or `x86-64-v2-AES`) that doesn't expose all of the host CPU's instruction sets to the VM, which causes ClickHouse to fail with `Illegal instruction` errors or get stuck in a restart loop.@@ -121,7 +128,7 @@ The `host` CPU type can prevent live migration between Proxmox nodes with differ## I ran out of disk space-Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from from this. There are two main reasons why you might have run out of disk space:+Regular web analytics events take up almost no space in Clickhouse, so it is very unlikely that you ran out of disk space from this. There are two main reasons why you might have run out of disk space:### 1. You are using session replay@@ -133,7 +140,8 @@ We have a 30 day retention policy for session replays events, so if you turn offdocker exec -it clickhouse clickhouse-client --database analyticsTRUNCATE TABLE session_replay_events;-TRUNCATE TABLE session_replay_metadata;+TRUNCATE TABLE session_replay_metadata_v2;+TRUNCATE TABLE session_replay_metadata; -- legacy table, only holds data from older versions```### 2. You didn't mount the Clickhouse log suppression configsdiff --git a/docs/content/docs/api/sending-events.mdx b/docs/content/docs/api/sending-events.mdxindex 1674743cb..a6234329b 100644--- a/docs/content/docs/api/sending-events.mdx+++ b/docs/content/docs/api/sending-events.mdx@@ -1,12 +1,13 @@---title: Sending Events-description: Track pageviews, custom events, performance, and errors from any platform using the HTTP API.+description: Track pageviews, custom events, and other events from any platform using the HTTP API.full: truemethod: POST---import { TypeTable } from 'fumadocs-ui/components/type-table';import { Tab, Tabs } from 'fumadocs-ui/components/tabs';+import { Callout } from 'fumadocs-ui/components/callout';<div className="grid grid-cols-1 xl:grid-cols-2 gap-8"><div>@@ -15,11 +16,19 @@ import { Tab, Tabs } from 'fumadocs-ui/components/tabs';POST /api/track```-Track pageviews, custom events, performance, and errors from server-side applications, mobile apps, or any platform. An API key is optional but recommended for server-side tracking β it bypasses bot detection and domain validation. IP addresses are resolved to geolocation and user agents are parsed for browser/OS/device info.+Send events from servers, mobile apps, or any platform that can make an HTTP request. The body is JSON, and every event needs a `site_id` and a `type`.++Send an API key as `Authorization: Bearer your_api_key_here` when you report events on a visitor's behalf. A key only counts here if it has access to the site and is full-access or holds the `ingest:write` permission. With such a key, Rybbit uses the `ip_address` and `user_agent` you send for the visitor ID, geolocation and device detection, and skips every bot check except user-agent classification. Without one (including a key sent as `?api_key=`), `ip_address` and `user_agent` are ignored and the event is treated as a browser hit from your server. They are still validated, so a malformed value returns `400`. There is no domain validation.++<Callout type="warn">+Bot detection still runs. Without a qualifying key, a request from a server HTTP client (curl, python-requests, node-fetch, Go's HTTP client and similar) is classified as a bot. With one, the reported user agent is still classified, so pass the visitor's real user agent. With bot blocking on (the default), bot events are stored as bot traffic and never appear in your analytics, but the response is still `200` with `{"success":true}`.+</Callout>++To keep visitors apart, send an `anonymous_id` per visitor, or the visitor's `ip_address` and `user_agent` with a qualifying key. Otherwise every event shares your server's IP and user agent and counts as one visitor.### Request Body-All parameters are sent in the request body as JSON.+All parameters are sent in the request body as JSON. Unknown fields are rejected with `400`, so don't add fields that aren't listed here.<TypeTabletype={{@@ -29,15 +38,20 @@ All parameters are sent in the request body as JSON.required: true,},type: {- description: 'Event type',+ description: 'Event type. Each type accepts the fields below plus the type-specific ones in its section.',type: 'string',- typeDescription: '"pageview" | "custom_event" | "performance" | "outbound" | "error"',- default: 'pageview',+ typeDescription: '"pageview" | "custom_event" | "performance" | "outbound" | "error" | "button_click" | "copy" | "form_submit" | "input_change"',+ required: true,},pathname: {- description: 'Page path',+ description: 'Page path. Site exclusions match the full value; it is stored cut to 2048 chars.',+ type: 'string',+ typeDescription: 'Max 16384 chars',+ },+ querystring: {+ description: 'Query string, e.g. "?utm_source=newsletter". Same limits as pathname.',type: 'string',- typeDescription: 'Max 2048 chars',+ typeDescription: 'Max 16384 chars',},hostname: {description: 'Domain name',@@ -45,55 +59,62 @@ All parameters are sent in the request body as JSON.typeDescription: 'Max 253 chars',},page_title: {- description: 'Page title',+ description: 'Page title. Longer values are cut.',type: 'string',- typeDescription: 'Max 512 chars',+ typeDescription: 'Stored up to 512 chars',},referrer: {- description: 'Referrer URL',+ description: 'Referrer URL. Longer values are cut.',type: 'string',- typeDescription: 'Max 2048 chars',+ typeDescription: 'Stored up to 2048 chars',},- user_id: {- description: 'Custom user identifier',+ anonymous_id: {+ description: 'Stable per-visitor ID. When set, the visitor is derived from it instead of IP and user agent.',type: 'string',- typeDescription: 'Max 255 chars',+ typeDescription: '1-255 chars',},- user_agent: {- description: 'Custom user agent string - will be parsed for browser/OS/device info',+ user_id: {+ description: 'Your ID for a signed-in user',type: 'string',- typeDescription: 'Max 512 chars',+ typeDescription: 'Max 255 chars',},ip_address: {- description: 'Custom IP for geolocation - will be resolved to location data',+ description: "Visitor's IP, used for geolocation and the visitor ID. Ignored without a qualifying Bearer key.",type: 'string',typeDescription: 'Valid IPv4 or IPv6 address',},- querystring: {- description: 'Query parameters',+ user_agent: {+ description: "Visitor's user agent, parsed for browser, OS and device. Ignored without a qualifying Bearer key.",type: 'string',- typeDescription: 'Max 2048 chars',+ typeDescription: 'Max 512 chars',},language: {description: 'Language code',type: 'string',- typeDescription: 'e.g., "en", "es", "fr"',+ typeDescription: 'Max 35 chars, e.g. "en-US"',},screenWidth: {description: 'Screen width in logical pixels (density-independent pixels)',type: 'number',+ typeDescription: 'Non-negative integer',},screenHeight: {description: 'Screen height in logical pixels (density-independent pixels)',type: 'number',+ typeDescription: 'Non-negative integer',+ },+ tag: {+ description: 'Free-form label stored with the event, e.g. a deployment or variant name',+ type: 'string',+ typeDescription: 'Max 256 chars',},event_name: {- description: 'Event name (required for custom events)',+ description: 'Event name. Required for custom_event and error, optional for the other types.',type: 'string',typeDescription: 'Max 256 chars',},properties: {- description: 'JSON string with event data (for custom events, outbound, error)',+ description: 'JSON string with event data. Its required shape depends on the type.',type: 'string',typeDescription: 'Max 2048 chars (4096 for error events)',},@@ -107,7 +128,7 @@ All parameters are sent in the request body as JSON.#### Pageview-Standard page view tracking. Set `type: "pageview"` (default).+Standard page view tracking. Set `type: "pageview"`.#### Custom Event@@ -122,7 +143,7 @@ Track custom events with optional properties. Set `type: "custom_event"`.required: true,},properties: {- description: 'Event data as JSON string',+ description: 'Event data as a JSON string. Only a JSON object is stored; other valid JSON (a string, number or array) is dropped and the event is kept.',type: 'string',typeDescription: 'Valid JSON, max 2048 chars',},@@ -165,13 +186,14 @@ Track Core Web Vitals. Set `type: "performance"`.#### Outbound-Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string.+Track outbound link clicks. Set `type: "outbound"`. Pass details in the `properties` JSON string; it is required for this type.<TypeTabletype={{url: {description: 'Destination URL',type: 'string',+ typeDescription: 'Absolute URL',required: true,},text: {@@ -188,7 +210,7 @@ Track outbound link clicks. Set `type: "outbound"`. Pass details in the `propert#### Error-Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and `properties` carries the error details as a JSON string.+Track JavaScript errors. Set `type: "error"`. `event_name` (required) is the error type and `properties` (required) carries the error details as a JSON string.<TypeTabletype={{@@ -218,20 +240,153 @@ Track JavaScript errors. Set `type: "error"`. `event_name` is the error type and}}/>-### Response+#### Button Click++Set `type: "button_click"`. `properties` is optional. Any valid JSON string is accepted, but only a JSON object is stored; other values are dropped and the event is kept.++#### Copy++Set `type: "copy"`. `properties` is required.<TypeTabletype={{- success: {- description: 'Whether the event was accepted',- type: 'boolean',+ sourceElement: {+ description: 'Element the text was copied from, e.g. "p" or "code"',+ type: 'string',+ required: true,+ },+ text: {+ description: 'Copied text',+ type: 'string',+ },+ textLength: {+ description: 'Length of the copied text',+ type: 'number',+ typeDescription: 'Non-negative',},}}/>+#### Form Submit++Set `type: "form_submit"`. `properties` is required, and every field below must be present.++<TypeTable+ type={{+ formId: {+ description: 'Form id attribute (empty string if none)',+ type: 'string',+ required: true,+ },+ formName: {+ description: 'Form name attribute (empty string if none)',+ type: 'string',+ required: true,+ },+ formAction: {+ description: 'Form action URL',+ type: 'string',+ required: true,+ },+ method: {+ description: 'HTTP method, e.g. "POST"',+ type: 'string',+ required: true,+ },+ fieldCount: {+ description: 'Number of fields in the form',+ type: 'number',+ typeDescription: 'Non-negative',+ required: true,+ },+ }}+/>++#### Input Change++Set `type: "input_change"`. `properties` is required.++<TypeTable+ type={{+ element: {+ description: 'Element type, e.g. "input" or "select"',+ type: 'string',+ required: true,+ },+ inputName: {+ description: 'Name or id of the field',+ type: 'string',+ required: true,+ },+ }}+/>++### Response++| Status | Body | Meaning |+|--------|------|---------|+| `200` | `{"success":true}` | Accepted. Events classified as bots get the same response. |+| `200` | `{"success":true,"message":"Event not tracked - ... excluded"}` | Matched one of the site's exclusions and was not stored. |+| `200` | Plain text, e.g. `Site over monthly limit, event not tracked` or `Site has no plan, event not tracked` | Not stored. The body is not JSON, so read it as text. |+| `400` | `{"success":false,"error":"Invalid payload","details":...}` | Validation failed; `details` lists the failing fields. |+| `404` | `{"success":false,"error":"Site not found"}` | Unknown `site_id`. |+### Rate Limiting-API keys are limited to **500 requests per 10 minutes**. Exceeding the limit returns a `429` status code.+`/api/track` itself isn't rate limited, but on Rybbit Cloud every request that carries a Bearer key counts against the key owner's API limits: a burst of 50 requests per 10 seconds, plus 5,000 (Standard) or 25,000 (Pro) requests per day. See [Rate Limits](/docs/api/getting-started#rate-limits-cloud-only).++When a limit is reached, `/api/track` doesn't return `429`. The key simply stops counting: the event is still ingested, but as untrusted traffic, so `ip_address` and `user_agent` are ignored and bot detection runs in full. Self-hosted instances have no API rate limits.++### Identifying Users++```+POST /api/identify+```++Links a visitor to your user ID and stores traits on the user's profile. This is the endpoint `rybbit.identify()` and `rybbit.setTraits()` call in the browser. Send the same `Authorization: Bearer` key as for `/api/track` if you pass `ip_address` or `user_agent`; without a qualifying key they're ignored.++<TypeTable+ type={{+ site_id: {+ description: 'Your site ID',+ type: 'string',+ required: true,+ },+ user_id: {+ description: 'Your ID for the user',+ type: 'string',+ typeDescription: '1-255 chars',+ required: true,+ },+ anonymous_id: {+ description: 'The anonymous_id you send with this visitor\'s events. When omitted, the visitor is derived from IP and user agent.',+ type: 'string',+ typeDescription: '1-255 chars',+ },+ ip_address: {+ description: "Visitor's IP. Used only with a qualifying Bearer key.",+ type: 'string',+ typeDescription: 'Valid IPv4 or IPv6 address',+ },+ user_agent: {+ description: "Visitor's user agent. Used only with a qualifying Bearer key.",+ type: 'string',+ typeDescription: 'Max 512 chars',+ },+ traits: {+ description: 'User properties to merge into the profile. A trait set to null is removed. username, name and email are shown in the dashboard.',+ type: 'object',+ typeDescription: 'Max 2 KB as JSON',+ },+ is_new_identify: {+ description: 'When true, links the visitor to user_id; the first time a visitor is linked, its anonymous events from the last 30 days are attributed to the user. Set false to only update traits.',+ type: 'boolean',+ default: 'true',+ },+ }}+/>++Responses: `200` with `{"success":true}`; `200` with the plain-text body `Site has no plan, identify not stored`; `400` for an invalid payload; `404` for an unknown site.</div><div className="flex flex-col gap-4">@@ -247,7 +402,10 @@ curl -X POST "https://app.rybbit.io/api/track" \"type": "custom_event","pathname": "/checkout","event_name": "purchase",- "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"+ "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}",+ "anonymous_id": "visitor-session-id",+ "ip_address": "203.0.113.7",+ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"}'```</Tab>@@ -264,11 +422,15 @@ const response = await fetch('https://app.rybbit.io/api/track', {type: 'custom_event',pathname: '/checkout',event_name: 'purchase',- properties: JSON.stringify({ amount: 99.99, currency: 'USD' })+ properties: JSON.stringify({ amount: 99.99, currency: 'USD' }),+ anonymous_id: 'visitor-session-id',+ ip_address: '203.0.113.7',+ user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36'})});-const data = await response.json();+// Some 200 responses are plain text, so read the body as text+const result = await response.text();```</Tab><Tab value="Python">@@ -283,14 +445,18 @@ response = requests.post('type': 'custom_event','pathname': '/checkout','event_name': 'purchase',- 'properties': json.dumps({'amount': 99.99, 'currency': 'USD'})+ 'properties': json.dumps({'amount': 99.99, 'currency': 'USD'}),+ 'anonymous_id': 'visitor-session-id',+ 'ip_address': '203.0.113.7',+ 'user_agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36'},headers={'Authorization': 'Bearer your_api_key_here'})-data = response.json()+# Some 200 responses are plain text, so read the body as text+result = response.text```</Tab><Tab value="PHP">@@ -300,7 +466,10 @@ $body = ['type' => 'custom_event','pathname' => '/checkout','event_name' => 'purchase',- 'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD'])+ 'properties' => json_encode(['amount' => 99.99, 'currency' => 'USD']),+ 'anonymous_id' => 'visitor-session-id',+ 'ip_address' => '203.0.113.7',+ 'user_agent' => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36'];$ch = curl_init();@@ -313,10 +482,9 @@ curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);-$response = curl_exec($ch);+// Some 200 responses are plain text, so treat the body as text+$result = curl_exec($ch);curl_close($ch);--$data = json_decode($response, true);```</Tab><Tab value="Ruby">@@ -333,14 +501,18 @@ request.body = {type: 'custom_event',pathname: '/checkout',event_name: 'purchase',- properties: { amount: 99.99, currency: 'USD' }.to_json+ properties: { amount: 99.99, currency: 'USD' }.to_json,+ anonymous_id: 'visitor-session-id',+ ip_address: '203.0.113.7',+ user_agent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36'}.to_jsonresponse = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|http.request(request)end-data = JSON.parse(response.body)+# Some 200 responses are plain text, so read the body as text+result = response.body```</Tab><Tab value="Go">@@ -350,7 +522,10 @@ body := map[string]interface{}{"type": "custom_event","pathname": "/checkout","event_name": "purchase",- "properties": `{"amount": 99.99, "currency": "USD"}`,+ "properties": `{"amount": 99.99, "currency": "USD"}`,+ "anonymous_id": "visitor-session-id",+ "ip_address": "203.0.113.7",+ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36",}jsonBody, _ := json.Marshal(body)@@ -362,8 +537,8 @@ client := &http.Client{}resp, _ := client.Do(req)defer resp.Body.Close()-var data map[string]interface{}-json.NewDecoder(resp.Body).Decode(&data)+// Some 200 responses are plain text, so read the body as text+result, _ := io.ReadAll(resp.Body)```</Tab><Tab value="Rust">@@ -373,7 +548,10 @@ let body = serde_json::json!({"type": "custom_event","pathname": "/checkout","event_name": "purchase",- "properties": r#"{"amount": 99.99, "currency": "USD"}"#+ "properties": r#"{"amount": 99.99, "currency": "USD"}"#,+ "anonymous_id": "visitor-session-id",+ "ip_address": "203.0.113.7",+ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"});let client = reqwest::Client::new();@@ -384,7 +562,8 @@ let res = client.send().await?;-let data: serde_json::Value = res.json().await?;+// Some 200 responses are plain text, so read the body as text+let result = res.text().await?;```</Tab><Tab value="Java">@@ -395,7 +574,10 @@ String json = """"type": "custom_event","pathname": "/checkout","event_name": "purchase",- "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}"+ "properties": "{\"amount\": 99.99, \"currency\": \"USD\"}",+ "anonymous_id": "visitor-session-id",+ "ip_address": "203.0.113.7",+ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"}""";@@ -418,7 +600,10 @@ var body = newtype = "custom_event",pathname = "/checkout",event_name = "purchase",- properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" })+ properties = JsonSerializer.Serialize(new { amount = 99.99, currency = "USD" }),+ anonymous_id = "visitor-session-id",+ ip_address = "203.0.113.7",+ user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36"};using var client = new HttpClient();@@ -430,7 +615,8 @@ var content = new StringContent("application/json");var response = await client.PostAsync("https://app.rybbit.io/api/track", content);-var data = await response.Content.ReadAsStringAsync();+// Some 200 responses are plain text, so read the body as text+var result = await response.Content.ReadAsStringAsync();```</Tab></Tabs>@@ -441,13 +627,13 @@ var data = await response.Content.ReadAsStringAsync();}```-```json title="Error"+```json title="Error (400, unknown field in the body)"{"success": false,"error": "Invalid payload","details": {- "fieldErrors": {},- "formErrors": ["Custom events require event_name"]+ "formErrors": ["Unrecognized key(s) in object: 'api_key'"],+ "fieldErrors": {}}}```