LiftCanary

Advanced

Self-hosting and deployment

Run the API, collector and dashboard yourself (Enterprise), with every setting explained.

LiftCanary is a set of small services. You can run all of them yourself, for example to keep every event in your own infrastructure. This page covers what each service needs and every setting.

Services#

ServiceDefault portNeedsRole
API (apps/api)4000Postgres; ClickHouse for resultsManagement API, datafile publishing, public datafiles, guardrail checks
Collector (apps/collector)4100ClickHouse, the APIReceives SDK event batches
Dashboard (apps/dashboard)3000The APIThe web app your team uses
CDN–The API as originServes datafiles, the snippet and /geo close to users

Run it with Docker#

One Dockerfile builds the three services (targets api, collector, dashboard; site is the marketing site), and docker-compose.prod.yml runs them with Postgres and ClickHouse. Every setting comes from .env; .env.example lists them.

Terminal
cp .env.example .env                  # fill in the passwords and INTERNAL_TOKEN (openssl rand -base64 48)
docker compose -f docker-compose.prod.yml up -d --build
docker compose -f docker-compose.prod.yml exec api node --import tsx apps/api/src/cli/create-org.ts "Acme"

Migrations run when the API and the collector start. Each container has a health check on /ready, and the collector and dashboard wait for a healthy API. The three ports listen on 127.0.0.1 only: put a reverse proxy or load balancer with HTTPS on the same machine in front of them (and a CDN in front of the API, below), or set API_BIND=0.0.0.0 to publish them on every interface. Docker's published ports bypass host firewalls such as ufw, so keep them private unless something else filters them.

The file's cloud profile adds what LiftCanary Cloud itself runs: the marketing site and a Caddy front door that gets HTTPS certificates through Cloudflare DNS (deploy/caddy). You don't need it to host LiftCanary yourself.

Local development#

Terminal
pnpm install
docker compose up -d                 # ClickHouse on 127.0.0.1:8123
cd apps/api && pnpm create-org "Acme"  # prints an API token (sk_...) once
pnpm dev                              # API on :4000, embedded Postgres in ./.data
Terminal
INTERNAL_TOKEN=change-me pnpm --filter @liftcanary/api dev
INTERNAL_TOKEN=change-me API_URL=http://localhost:4000 pnpm --filter @liftcanary/collector dev
LIFTCANARY_API_URL=http://localhost:4000 pnpm --filter @liftcanary/dashboard dev

Without DATABASE_URL the API uses an embedded Postgres (PGlite) on disk, so local development needs no database server. Migrations run automatically on start.

Settings#

API#

DATABASE_URL
postgres://…
Postgres connection string. pglite://./.data (the default) for an embedded database.
CLICKHOUSE_URL
http://user:pass@host:8123/db
Analytics warehouse. Without it, results endpoints answer 503 analytics_unavailable.
INTERNAL_TOKEN
secret
Shared with the collector for SDK-key and webhook lookups. Use the same long random value on both. It also encrypts the billing webhooks' secret keys (Paddle): after changing it, paste them in again under Integrations.
PORT
number
Default 4000.
TRUST_PROXY
1
Set behind a load balancer so sign-in rate limits use the client address from X-Forwarded-For.
GUARDRAIL_INTERVAL_SECONDS
number
How often running experiments' guardrails are checked. Default 300; 0 turns automatic checks off.
SDK_BUNDLE_PATH
path
Where the snippet bundle served at /sdk/v1/liftcanary.js is read from. Default: the built packages/js.
SDK_BUNDLE_DIR
path
Folder with liftcanary.js and editor.js (the visual editor). Default: packages/js/dist.
LOG_FORMAT
"json" | "pretty"
One JSON object per line (default in production) or readable lines. Each request is logged with its id (X-Request-Id, kept from your proxy), method, path, status and duration; errors with their stack.
LOG_LEVEL
"debug" | "info" | "warn" | "error"
Default info. Datafile and snippet requests are logged at debug.
API_RATE_LIMIT_PER_MINUTE
number
Requests per minute per API token or session on /v1; over it: 429 with Retry-After. Default 1200; 0 = unlimited. Counted per API process.
CDN_PURGE
"cloudflare" | "webhook"
Purge datafiles from the CDN right after each publish (see below). Unset: the CDN keeps them for 10 seconds.
CDN_PUBLIC_URL
URL
The CDN address visitors load datafiles from, e.g. https://cdn.example.com. Required with CDN_PURGE.
CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKEN
string
For CDN_PURGE=cloudflare: the zone and a token with the Cache Purge permission.
CDN_PURGE_WEBHOOK_URL
URL
For CDN_PURGE=webhook: receives POST { "urls": [...] } to purge on any other CDN.
MAIL_PROVIDER
"resend" | "log"
Send email (invitations, password resets, confirmations, notifications) through Resend. log writes emails to the log instead, with their links: enough for trying it out, but anyone who reads the logs can use them. Unset, development does the same, and production sends nothing.
RESEND_API_KEY
string
With MAIL_PROVIDER=resend.
ANTHROPIC_API_KEY
string
Turns on AI suggestions in the visual editor (Claude API). Unset: the editor doesn't offer them.
AI_MODEL
string
The Claude model that writes them. Default claude-haiku-5-5, about a tenth of a cent per suggestion; claude-sonnet-5-5 or claude-opus-5-5 write more carefully and cost more.
MAIL_FROM
string
The sender, e.g. "LiftCanary <[email protected]>", on a domain verified with the provider. Quote it in .env if a shell script reads the file (the backup scripts do).
DASHBOARD_URL
URL
The dashboard's public address, used for links in emails. Default http://localhost:3000.
LIFTCANARY_SITE_URL
URL
Where emails load the logo (/email/liftcanary-mark.png) and link to in their footer. Default https://liftcanary.com.
ENFORCE_USAGE_LIMITS
1
Stop collecting data for organizations past their visitor limit × USAGE_GRACE (with PLAN_LIMITS, only Free organizations). Unset: limits only warn.
PLAN_LIMITS
1
LiftCanary Cloud's plans: limits and paid features apply per organization. Leave it unset when you host LiftCanary yourself: every feature is included and only limits you set apply.
PADDLE_API_KEY, PADDLE_WEBHOOK_SECRET, PADDLE_CLIENT_TOKEN, PADDLE_PRICES
string
Self-serve subscriptions through Paddle (needs PLAN_LIMITS). PADDLE_PRICES maps plans to Paddle prices: starter.monthly=pri_…,starter.annual=pri_…,growth.monthly=pri_…. Point Paddle's webhook at /billing/paddle/webhook on the API and its default payment link at the dashboard's /checkout.
PADDLE_ENVIRONMENT
"sandbox" | "production"
Default sandbox.
USAGE_GRACE
number
How far past the limit collection continues when enforced. Default 1.1 (10%).
DEV_GEO
TR,34,Istanbul
Country, region and city answered by /geo when no CDN headers are present (local development).
DATA_PLANE_SECRET
secret
For hybrid deployment: a random value of at least 32 characters that customers' license keys are derived from. Changing it revokes every key. Unset: hybrid deployment is unavailable. Allow it per organization with pnpm --filter @liftcanary/api hybrid <organization id> on.
NODE_ENV
production
Caches the snippet bundle and turns on the production checks: the API refuses to start without a postgres:// DATABASE_URL, an INTERNAL_TOKEN of at least 32 characters and CLICKHOUSE_URL.

Every setting is checked when the service starts; a wrong one stops it with a message naming the setting.

Collector#

API_URLrequired
URL
The API, for SDK-key lookups.
INTERNAL_TOKENrequired
secret
Same value as the API's.
LICENSE_KEY
lk_…
Instead of INTERNAL_TOKEN, when the collector is a customer's data plane in hybrid deployment.
DEV_GEO
TR,34,Istanbul
What the collector's own /geo answers without CDN headers.
CLICKHOUSE_URL
URL
Default: the docker compose instance. Required in production.
PORT
number
Default 4100.
COLLECTOR_RATE_PER_IP
number
Batches per minute per client address. Default 3000 (offices share an address); 0 = unlimited.
COLLECTOR_RATE_PER_KEY
number
Batches per minute per SDK key. Default 60,000; 0 = unlimited.
TRUST_PROXY
1
Use the first X-Forwarded-For address as the client (behind a CDN or load balancer).
LOG_FORMAT
"json" | "pretty"
As for the API.

Dashboard#

LIFTCANARY_API_URLrequired
URL
The API, as reached from the dashboard's server.
DASHBOARD_URL
URL
The dashboard's public address, used in invitation links.
LIFTCANARY_PUBLIC_SDK_URL
URL
Your CDN, used in the install snippets shown to your team.
LIFTCANARY_PUBLIC_EVENTS_URL
URL
Your collector's public address, for the same snippets.
LIFTCANARY_SITE_URL
URL
Your marketing site with the docs. Adds Docs and Website links under the sign-in and sign-up pages; hidden when unset.

Marketing site and docs#

NEXT_PUBLIC_APP_URL
URL
The dashboard address used for “Sign in” and “Start free” links.

CDN#

Put a CDN in front of the API for /datafiles/*, /stream/*, /sdk/v1/* and /geo. Datafiles are sent with max-age=10 for browsers. Without a purge the CDN keeps them 10 seconds too, so a change reaches visitors within about 20 seconds. With CDN_PURGE the CDN may keep them for 10 minutes (s-maxage=600), which takes most requests off the API, and every publish purges the changed datafiles at once (again 5 seconds later, in case the CDN fetched one while the change was being saved). A failed purge is logged; the CDN then serves the previous version until its cache time runs out.

Live updates. Server SDKs (Node.js, Python) keep /stream/:sdkKey open on the same host to hear about each publish in about a second. Pass it through the CDN and your proxy without caching or buffering: it's sent as text/event-stream with no-store, no-transform and a comment every 25 seconds (Cloudflare and Caddy pass it on as is; on nginx, turn off proxy_buffering for that path). If it doesn't get through, SDKs simply keep polling every 30 seconds. With several API instances, each one hears about publishes from Postgres (LISTEN), so it doesn't matter which instance an SDK is connected to.

The snippet is about 19 KB gzipped (the visual editor, loaded only when editing, about 11 KB). A test fails the build if they grow past 20 KB and 14 KB.

Usage limits#

Usage is counted in tested visitors: distinct ids that entered at least one experiment in the calendar month (UTC). Flags and rollouts don't count. Organization members see the count, per project, under Settings → Usage, and a warning on every page from 80% of the limit. A self-hosted installation has no limits unless you set one for an organization:

Terminal
pnpm --filter @liftcanary/api set-limit <organization id> 100000   # or "unlimited", or "plan" for the plan's

With ENFORCE_USAGE_LIMITS=1, an organization past its limit × USAGE_GRACE stops being collected: the collector answers 402 usage_limit_exceeded and SDKs drop those events. Flags, experiments and the snippet keep working; only new results stop. Counts are refreshed every 5 minutes.

With PLAN_LIMITS=1 (LiftCanary Cloud), each organization's plan sets its limit, projects, seats and paid features, and only Free organizations are ever stopped. Without Paddle, operators put an organization on a plan themselves:

Terminal
pnpm --filter @liftcanary/api set-plan <organization id> growth   # free | starter | growth | scale | enterprise

Capacity#

Measured with the load test below on one laptop (Apple M2, ClickHouse in Docker) for 100,000 simulated website visitors. A visitor-month is about 4 batches and 13 rows (exposures, page views, clicks, purchases).

PartMeasured
CollectorOver 1,300 batches a second at 256 connections with a 190 ms median response (the load generator was the limit), about 4,000 batches per CPU-second, 310 MB of memory.
ClickHouse storageAbout 740 bytes per visitor-month after compression: roughly 10 KB per visitor over the 400-day retention, 10 GB per million monthly visitors.
Dashboard queriesExperiment results, segments and funnels in 90 to 180 ms for an experiment with 100,000 visitors. Time grows with the experiment's size.
CDNA datafile with 10 flags and 2 experiments is 2.5 KB (under 0.5 KB gzipped); the snippet is 19 KB gzipped and cached by browsers.

The collector answers each batch once it is stored: batches that arrive within 100 ms share one insert per table, and if the insert fails every one of them gets 503 and the SDKs send them again. To measure your own setup, run the load test against a collector of its own (rate limits off,CLICKHOUSE_URL on a separate database); it creates a throwaway organization and deletes it at the end.

Terminal
INTERNAL_TOKEN=$INTERNAL_TOKEN COLLECTOR_RATE_PER_IP=0 COLLECTOR_RATE_PER_KEY=0 CLICKHOUSE_URL=http://user:pass@host:8123/loadtest PORT=4199 pnpm --filter @liftcanary/collector start
LOADTEST_COLLECTOR_URL=http://localhost:4199 LOADTEST_CLICKHOUSE_URL=http://user:pass@host:8123/loadtest LOADTEST_VISITORS=100000 \
  pnpm --filter @liftcanary/api load-test

Health and monitoring#

  • GET /health (API and collector): the process answers. Use it for liveness.
  • GET /ready: the API checks Postgres and ClickHouse, the collector ClickHouse; 503 with the failing check otherwise. Use it for readiness and load balancers.
  • Logs are JSON lines on stdout (errors on stderr for the collector): ship them to your log tool and alert on level: "error" and on status 5xx.

Backups#

scripts/backup.sh backs up both databases of the Docker setup into ./backups/<time>/ and keeps the last 14. Run it daily from cron and copy the folder off the machine.

Terminal
./scripts/backup.sh
# Restore Postgres (configuration, users, audit log):
docker compose -f docker-compose.prod.yml exec -T postgres pg_restore -U liftcanary -d liftcanary --clean < backups/<time>/postgres.dump
# Restore ClickHouse (events and exposures): copy the archive in, then
#   RESTORE DATABASE liftcanary FROM File('/var/lib/clickhouse/backups/<time>.zip')

Postgres is small and holds everything you configured, and the saved results of ended experiments: back it up at least daily. ClickHouse holds the raw events behind results; it can be large, so a weekly full backup plus your provider's snapshots is usually enough.

Production checklist#

  • Run Postgres and ClickHouse as managed or replicated services, or use the Docker setup with daily backups.
  • Put a CDN in front of the API for /datafiles/*, /sdk/v1/liftcanary.js and /geo, and let it pass its geo headers (Cloudflare, Vercel or CloudFront headers are read automatically).
  • Serve the collector under its own hostname, or behind your site through the first-party proxy.
  • Generate a long random INTERNAL_TOKEN. A mismatch makes the API answer 401 and the collector 503, so SDKs retry instead of losing events.
  • Set TRUST_PROXY=1 only when a proxy you control sets X-Forwarded-For.
  • Serve the dashboard over HTTPS; its session cookie is Secure in production.

Security notes#

  • Request bodies are limited: API 1 MB, collector 512 KB (streamed bytes are counted).
  • Rate limits: the management API per token or session, the collector per client address and per SDK key; both answer 429 with Retry-After, and SDKs keep their events and retry.
  • Sign-in: an e-mail address is locked for 15 minutes after 10 failures; one client address is limited to 100 failures per 15 minutes across addresses. Attempts are counted before the password check, so parallel guesses can't exceed the limit.
  • API tokens and sessions are stored as SHA-256 hashes; passwords with scrypt; recovery codes and emailed links as SHA-256 hashes.
  • Two-step sign-in (TOTP, RFC 6238) is optional per person; the authenticator secrets are stored in the database, so protect its backups like the database itself.
  • Regular expressions in audiences, URL rules and goals are checked for catastrophic backtracking when saved and again in the SDK; text over 1,024 characters never matches a regex.
  • Every query is scoped to the caller's organization; another tenant's resources answer 404.