Overview

@cookiepal-oss/backend is an optional HTTP service that captures consent records into Postgres. It's only needed if you want a proof-of-consent audit trail — the banner works without it.

Why self-host

• Data stays on your infra. No third-party processor, no analytics pixel, no outbound call to a SaaS.
• Server-stamped metadata. The banner's BackendLogger only sends { consentId, consent }. The backend stamps timestamp, IP, User-Agent, and — if you're behind Cloudflare, Vercel, CloudFront, or Amazon — country and region from edge headers. Client-sent metadata is ignored.
• Single-tenant per instance. One backend process serves one site. Clean blast radius, clean CORS, clean data.

How it connects to the banner

Set backendURL in the banner config (via the dashboard Settings, or directly in CookiepalConfig). The runtime POSTs consent events there whenever a user accepts / rejects / saves preferences.

const config: CookiepalConfig = {
  categories: [...],
  backendURL: 'https://consent.example.com',
};

Runtime stack

Built on Hono + pg on Node.js 22+. Ships as:

• An npm package: @cookiepal-oss/backend
• A multi-arch Docker image: ghcr.io/cookiepal/backend:<version> and :latest (amd64 + arm64)

Scale model

One container per site. If you're running ten sites, run ten backend instances — each with its own SITE, its own Postgres database, and its own ORIGINS allowlist. There is no multi-tenant routing.

Next

• Configuration — env vars, Postgres setup, migrations.
• Docker deployment — image, docker-compose, platform recipes.