Sarge
Docs
Self-hosted

Run Sarge in your own infrastructure.

Self-hosted Sarge is for teams that want the event API and database in their own cloud while keeping the same lightweight browser pixel and tracking model.

Deployment shape

Website/App
  -> Sarge pixel
  -> Sarge API container
  -> Postgres

Required environment variables

DATABASE_URL="postgresql://user:password@host:5432/sarge?schema=public"
PORT="49828"
NODE_ENV="production"

Pixel snippet

<script src="https://events.example.com/index.global.js"></script>
<script>
  sarge('init', {
    siteId: 'site_123',
    endpoint: 'https://events.example.com',
    attributionTtlDays: 28
  });

  sarge('track', 'PageView');
</script>

Test event

curl -X POST "https://events.example.com/v2/events" \
  -H "content-type: application/json" \
  -d '{
    "siteId": "site_123",
    "name": "TestEvent",
    "occurredAt": "2026-06-19T12:00:00.000Z",
    "sessionId": "manual_test_session",
    "userId": "manual_test_user",
    "properties": { "source": "curl" }
  }'

Expected response: { "success": true }

Preferred provider suggestions

The cleanest self-hosted setup keeps the database boring, the ingest endpoint close to users, and the portal deploy flow familiar.

Cloudflare

Best for the pixel edge and hosted endpoint

Use Workers for ingestion, CDN/caching for the pixel, DNS for endpoint hosts, and Workers AI later if you want scheduled diagnostics close to the edge.

Neon

Preferred Postgres

Use Neon for the event store, branching, pooled connections, and a low-maintenance Postgres control plane.

Fly.io

Simple API container hosting

Good fit when you want to run the Sarge API as a normal container with regional placement and straightforward custom domains.

Vercel

Good for portal or docs surfaces

Use Vercel for the frontend/admin app if your team prefers its deploy workflow. Keep high-volume ingestion on Cloudflare or Fly unless you have a specific reason.