Environment variables

The main environment variables used by the Callra web app, collector, and deployment workflows.

Use .env.example as the starting point for local and Node-based workflows.

Core app settings

APP_URL: public base URL used for generated snippets and links
SESSION_SECRET: secret used for application sessions and signing flows

Control-plane database

CONTROL_DATABASE_URL: Postgres or Neon connection string used by Node scripts and local development for users, sites, domains, sessions, API keys, and tracker sessions

Analytics database

Provide values for the analytics database connection:

host
query port
HTTP port
database name
username
password

The exact variable names live in .env.example and your deployment configuration. These values connect the app to the analytics database used for queries and maintenance workflows.

Collector and tracker behavior

TRACKER_SECRET: optional dedicated HMAC secret for tracker bootstrap tokens
TRACKER_SESSION_TTL_SECONDS: lifetime of tracker bootstrap sessions
COLLECTOR_BODY_LIMIT_BYTES: request size limit for collector payloads
RESPECT_DNT_DEFAULT: default DNT and GPC behavior for new sites
RAW_RETENTION_DAYS: raw event retention window

Proxy and geo headers

TRUST_PROXY: whether reverse-proxy headers should be trusted
TRUSTED_IP_HEADER: header name used for the client IP when proxy trust is enabled
TRUSTED_COUNTRY_HEADER: header name used for the client country when proxy trust is enabled

On Cloudflare, the common values are:

TRUST_PROXY=true
TRUSTED_IP_HEADER=cf-connecting-ip
TRUSTED_COUNTRY_HEADER=cf-ipcountry

Bootstrap and admin helpers

ADMIN_EMAIL: optional email for automated first boot
ADMIN_PASSWORD: optional password for automated first boot

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET
GITHUB_ADMIN_EMAIL

These enable GitHub OAuth sign-in and optional admin bootstrap behavior for a pre-approved GitHub email.

Ingest and internal service calls

CALLRA_INGEST_BASE_URL: base URL for the dedicated ingest service
CALLRA_INTERNAL_TOKEN: internal token for control-plane requests between services

When the web app runs on Cloudflare Workers, database access goes through Hyperdrive bindings at request time. CONTROL_DATABASE_URL is still needed for Node-side scripts such as migrations and admin bootstrapping.