Self-hosting

Environment variables, database setup, background workers, scheduler, seed data and the end-to-end verification suite.

Updated 2026-09-02

Requirements#

Node 22+, pnpm, PostgreSQL 14+ (16 recommended), optional Redis 7, optional Cloudflare account for the edge worker.

Environment#

Variable	Purpose
`DATABASE_URL`	Postgres connection string
`AUTH_SECRET`	JWT signing secret for `wc_session`
`NEXT_PUBLIC_APP_URL`	Control-plane origin (`https://app.whichclick.is`)
`NEXT_PUBLIC_TRACKING_DOMAIN`	Default tracking hostname
`REDIS_URL`	Optional — cache, streams, rate limits
`EDGE_INGEST_SECRET`	HMAC secret shared with the edge worker
`CREDENTIALS_KEY`	32-byte key for encrypting partner credentials
`ANTHROPIC_API_KEY`	Optional — in-dashboard assistant
`IPINFO_TOKEN`	Optional — live IP intel fallback
`RESEND_API_KEY`, `ALERT_FROM_EMAIL`	Optional — e-mail alert channel
`OAUTH_GOOGLE_CLIENT_ID` / `_SECRET`, `GOOGLE_ADS_DEVELOPER_TOKEN`	"Connect with Google" for Google Ads + platform developer token
`OAUTH_META_APP_ID` / `_SECRET`, `OAUTH_TIKTOK_APP_ID` / `_SECRET`, `OAUTH_SNAP_CLIENT_ID` / `_SECRET`, `OAUTH_PINTEREST_APP_ID` / `_SECRET`, `OAUTH_REDDIT_CLIENT_ID` / `_SECRET`, `OAUTH_LINKEDIN_CLIENT_ID` / `_SECRET`	Partner OAuth apps (redirect URI `$NEXT_PUBLIC_APP_URL/api/oauth/<partner>/callback`)

Setup#

Shell

cp .env.example .env
docker compose up -d          # local Postgres (optional)
pnpm install
pnpm db:push                  # schema
pnpm db:scale                 # BRIN / GiST indexes, partitions
pnpm db:seed                  # demo organization, apps, protection data
pnpm dev                      # http://localhost:3000

Demo login [email protected] / demo-password-123; demo API key wc_live_demo_0123456789abcdef; SDK keys sk_demo_ios_0123456789, sk_demo_android_0123456789.

Background processes#

Command	What it does
`pnpm worker`	Consumes the Redis click stream into Postgres (only with `REDIS_URL`)
`pnpm scheduler`	Alerts, cost sync, uninstall checks, TV attribution, IP-pool sync, retention purge
`pnpm rollup`	Daily stat rollups (also run by the scheduler)
`pnpm ippool:sync`	Refresh the IP pool from public sources
`pnpm cost:sync`	One-off cost sync
`pnpm uninstall:check`	One-off silent-push uninstall check

Verification#

pnpm verify runs 45 end-to-end checks against the running server: transparent redirect contract, domain binding, ValueTrack persistence, async fraud scoring, smart-link routing, every attribution method, events → LTV, postbacks, cost import, protection flows and a latency benchmark. Run it after any change to redirect, attribution or protection code.

pnpm test runs unit tests (redirect resolver, routing engine, integrations, subscriptions, uninstall).

Production notes#

Run next build && next start behind a TLS terminator; set NEXT_PUBLIC_APP_URL accordingly.
Put the edge worker in front of tracking domains for global latency; the control plane can stay in one region.
Back up Postgres daily; clicks are partitioned monthly so old partitions can be archived.
Rotate AUTH_SECRET and API keys per your policy; the audit log records key usage.