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#
| Service | Default port | Needs | Role |
|---|---|---|---|
| API (apps/api) | 4000 | Postgres; ClickHouse for results | Management API, datafile publishing, public datafiles, guardrail checks |
| Collector (apps/collector) | 4100 | ClickHouse, the API | Receives SDK event batches |
| Dashboard (apps/dashboard) | 3000 | The API | The web app your team uses |
| CDN | – | The API as origin | Serves 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.
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#
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 ./.dataINTERNAL_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 devWithout 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_URLpostgres://… | Postgres connection string. pglite://./.data (the default) for an embedded database. |
CLICKHOUSE_URLhttp://user:pass@host:8123/db | Analytics warehouse. Without it, results endpoints answer 503 analytics_unavailable. |
INTERNAL_TOKENsecret | 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. |
PORTnumber | Default 4000. |
TRUST_PROXY1 | Set behind a load balancer so sign-in rate limits use the client address from X-Forwarded-For. |
GUARDRAIL_INTERVAL_SECONDSnumber | How often running experiments' guardrails are checked. Default 300; 0 turns automatic checks off. |
SDK_BUNDLE_PATHpath | Where the snippet bundle served at /sdk/v1/liftcanary.js is read from. Default: the built packages/js. |
SDK_BUNDLE_DIRpath | 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_MINUTEnumber | 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_URLURL | The CDN address visitors load datafiles from, e.g. https://cdn.example.com. Required with CDN_PURGE. |
CLOUDFLARE_ZONE_ID, CLOUDFLARE_API_TOKENstring | For CDN_PURGE=cloudflare: the zone and a token with the Cache Purge permission. |
CDN_PURGE_WEBHOOK_URLURL | 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_KEYstring | With MAIL_PROVIDER=resend. |
ANTHROPIC_API_KEYstring | Turns on AI suggestions in the visual editor (Claude API). Unset: the editor doesn't offer them. |
AI_MODELstring | 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_FROMstring | 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_URLURL | The dashboard's public address, used for links in emails. Default http://localhost:3000. |
LIFTCANARY_SITE_URLURL | Where emails load the logo (/email/liftcanary-mark.png) and link to in their footer. Default https://liftcanary.com. |
ENFORCE_USAGE_LIMITS1 | Stop collecting data for organizations past their visitor limit × USAGE_GRACE (with PLAN_LIMITS, only Free organizations). Unset: limits only warn. |
PLAN_LIMITS1 | 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_PRICESstring | 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_GRACEnumber | How far past the limit collection continues when enforced. Default 1.1 (10%). |
DEV_GEOTR,34,Istanbul | Country, region and city answered by /geo when no CDN headers are present (local development). |
DATA_PLANE_SECRETsecret | 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_ENVproduction | 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_URLrequiredURL | The API, for SDK-key lookups. |
INTERNAL_TOKENrequiredsecret | Same value as the API's. |
LICENSE_KEYlk_… | Instead of INTERNAL_TOKEN, when the collector is a customer's data plane in hybrid deployment. |
DEV_GEOTR,34,Istanbul | What the collector's own /geo answers without CDN headers. |
CLICKHOUSE_URLURL | Default: the docker compose instance. Required in production. |
PORTnumber | Default 4100. |
COLLECTOR_RATE_PER_IPnumber | Batches per minute per client address. Default 3000 (offices share an address); 0 = unlimited. |
COLLECTOR_RATE_PER_KEYnumber | Batches per minute per SDK key. Default 60,000; 0 = unlimited. |
TRUST_PROXY1 | 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_URLrequiredURL | The API, as reached from the dashboard's server. |
DASHBOARD_URLURL | The dashboard's public address, used in invitation links. |
LIFTCANARY_PUBLIC_SDK_URLURL | Your CDN, used in the install snippets shown to your team. |
LIFTCANARY_PUBLIC_EVENTS_URLURL | Your collector's public address, for the same snippets. |
LIFTCANARY_SITE_URLURL | 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_URLURL | 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:
pnpm --filter @liftcanary/api set-limit <organization id> 100000 # or "unlimited", or "plan" for the plan'sWith 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:
pnpm --filter @liftcanary/api set-plan <organization id> growth # free | starter | growth | scale | enterpriseCapacity#
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).
| Part | Measured |
|---|---|
| Collector | Over 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 storage | About 740 bytes per visitor-month after compression: roughly 10 KB per visitor over the 400-day retention, 10 GB per million monthly visitors. |
| Dashboard queries | Experiment results, segments and funnels in 90 to 180 ms for an experiment with 100,000 visitors. Time grows with the experiment's size. |
| CDN | A 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.
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-testHealth 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;503with 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.
./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.jsand/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=1only when a proxy you control setsX-Forwarded-For. - Serve the dashboard over HTTPS; its session cookie is
Securein 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
429withRetry-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.