Configuration reference

A self-hosted instance is configured through one env file, .env in the repository root next to docker-compose.yml, written by backend/scripts/setup.sh and edited by you (or rendered from Doppler). This page lists every setting the API reads, every setting the compose file reads, and what the compose file sets for you.

How settings are readCopy Anchor Link

• The API gets the whole env file. docker-compose.yml hands .env to the api container (env_file), so every line reaches it, passwords included, but for PGBACKREST_REPO1_CIPHER_PASS, which compose blanks for it. The postgres, pgbackrest, clickhouse and valkey containers only get the values compose names for them, and cloudflared only the tunnel token.

• Compose reads the same file for its own settings (the store passwords, the backup passphrase, memory limits): run every docker compose command from the repository root, where it finds both docker-compose.yml and .env.

• Some API settings are fixed by compose. The api service's environment: block wins over the env file, so a value you put in .env for one of those has no effect. They are listed in Set by the compose file.

• A blank value is unset. KEY= (or only spaces) counts as not set, so the default applies and a required key is reported missing.

• Invalid settings stop the API at start. It exits with code 1 after logging one JSON line at level fatal ("level":60, "msg":"failed to start") whose err.message holds one KEY: reason line per invalid variable, never the values; docker compose logs api shows it, and Docker keeps restarting the container until the setting is fixed. For example, with TRUST_PROXY=true, SIGNUP_POLICY=closed, LIVE_MAX_GUEST_STREAMS=0, only R2_BUCKET of the four R2_* values, and LOG_LEVEL=trace with NODE_ENV=production, the message reads:

  Copy Text

  TRUST_PROXY: blanket "true" is forbidden; use false or a comma list of proxy IPs/CIDRs/names (e.g. loopback)
  SIGNUP_POLICY: Invalid option: expected one of "invite_only"|"open"
  LIVE_MAX_GUEST_STREAMS: must be at least 1
  R2_ACCOUNT_ID: required when any other R2_* setting is set (all or none)
  R2_ACCESS_KEY_ID: required when any other R2_* setting is set (all or none)
  R2_SECRET_ACCESS_KEY: required when any other R2_* setting is set (all or none)
  LOG_LEVEL: must not be trace when NODE_ENV=production (use debug at most)

• A change takes effect when the container is recreated. After editing .env (or a secret in Doppler), run docker compose up -d (with Doppler: backend/scripts/compose-doppler.sh up -d): compose recreates the containers whose settings changed.

The tables below give each setting's type and default as the code has them. The Type column names the accepted values where the code restricts them.

InstanceCopy Anchor Link

Databases and ValkeyCopy Anchor Link

Sign-up and sign-inCopy Anchor Link

MailCopy Anchor Link

Mail leaves through the REST API of Cloudflare Email Sending when CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_EMAIL_TOKEN are set, else through the SMTP server of SMTP_URL (local development, or an instance with its own mail server), else not at all: the API logs that a mail was skipped, an inviter sees the invite link to pass on, and sign-up stays invite-only. Password resets, email sign-in codes, email changes, emailed reports and new-sale emails all need mail. Slack and Discord new-sale messages do not.

With Cloudflare, the API makes up to three attempts per mail when Cloudflare answers 429 or 5xx, times out (10 seconds) or cannot be reached, waiting 1 then 2 seconds, or the Retry-After Cloudflare asks for when that is at most 10 seconds. Any other error, or a recipient Cloudflare reports as permanently bounced or suppressed, fails that mail at once. Each failure is logged with Cloudflare's error codes and the recipient's domain only, never the token, the address or the message. Cloudflare refuses a whole message for a header it does not accept, so only the headers it allows are sent: with an http:// PUBLIC_URL, emailed reports go without their one-click unsubscribe headers (Cloudflare takes only https: and mailto: links there), and the link in the email still works.

How the account-mail budgets work:

• Each budget is checked before the request runs, and counted in Valkey. If Valkey cannot be reached, the request fails (500) rather than send unbudgeted mail.
• A 429 from a budget carries an X-Retry-After header with the budget's window in seconds; the app tells the person to wait and try again.
• No budget covers the whole instance: anyone could spend it and stop everyone's mail. Set AUTH_MAIL_ALERT_PER_HOUR under your mail provider's sending limit and alert on its log line instead.
• Raise AUTH_MAIL_CLIENT_PER_HOUR if more than about 50 people sign in with emailed codes from one network address (an office behind one NAT) in the same hour, and AUTH_MAIL_INVITER_PER_HOUR before one admin invites more than 50 people in an hour (or invite them over two hours).
• An email change's confirmation link works once.

GeoIP (MaxMind)Copy Anchor Link

PilotFox locates visitors with MaxMind's GeoLite2 databases from your own free MaxMind account; they are never in an image. The API reads GeoLite2-City.mmdb and GeoLite2-ASN.mmdb from GEOIP_DIR (the geoip volume). Without them, the location and network columns of new events stay empty, the internal readiness check reports geoip: "missing", and nothing fails. Cloudflare's visitor location headers fill in the locations MaxMind cannot place (GEOIP_FALLBACK, Cloudflare).

The built-in updater (GEOIP_AUTO_DOWNLOAD=maxmind, what setup.sh writes). The geoip.refresh job downloads both editions on every start of a process with workers (APP_ROLE all or worker) and then every 6 hours (00:00, 06:00, 12:00 and 18:00 UTC). It asks MaxMind first whether the edition is newer than the file on disk, so a restart costs no download. A failed download keeps the previous file; a run that still fails after its retries counts as failed under Admin → Jobs. It needs to reach download.maxmind.com and the host it redirects downloads to. To download by hand (optional: every start does it), for example to see the result, from the repository root:

docker compose run --rm -T --no-deps api node dist/ops/geoip-download.js

It prints GeoLite2-City: updated and GeoLite2-ASN: updated (unchanged when there is nothing new), and exits 1 when the keys are missing or a download failed. The GeoLite licence wants old databases replaced within 30 days of a new release.

The API notices changed files within 10 minutes, without a restart. To check (the route is not public; this prints ok once both files are loaded):

docker compose exec -T api \
  node -e "fetch('http://127.0.0.1:3001/api/v1/ready').then((r) => r.json()).then((j) => console.log(j.data.geoip))"

Object storage (Cloudflare R2)Copy Anchor Link

Session replay, imports and backups store files in an R2 bucket, and Postgres archives every change to it (Backups and restore). Without the four R2_* values, replay is off, an import upload answers 503, and there are no backups. The R2 API token needs Object Read & Write on the bucket, plus Admin Read & Write if the backups should maintain their retention rule (otherwise delete old backups by hand). Scope it to this bucket: backups contain password hashes, hashed API keys and share tokens.

Backups also read two settings of their own, documented under Backups.

Google Search ConsoleCopy Anchor Link

Organization admins connect a Google account once (Organization settings → Integrations) and editors link each site to one of its Search Console properties. It needs an OAuth client in a Google Cloud project of yours; until one is configured, the Search Console pages show the setup steps and the redirect URI.

Redirect URI: ${PUBLIC_URL}/api/v1/search-console/oauth/callback, for example https://analytics.example.com/api/v1/search-console/oauth/callback. Google compares it exactly (scheme, host, port, path, no trailing slash). When Search Console shares the sign-in client, add this URI to that client next to its sign-in redirect URI.

One-time setup in the Google Cloud console:

Refresh tokens are stored encrypted with a key derived from BETTER_AUTH_SECRET; changing that secret turns the connections to "Reconnect". What Search Console shows and who can link what is in Search Console.

MapsCopy Anchor Link

The boundary archive is built from the repository (tools/boundaries/dist/boundaries.pmtiles) and copied into the maps volume: see Deploy.

Ingest and queriesCopy Anchor Link

Per-organization limitsCopy Anchor Link

These keep one organization from taking what the whole instance has. On an instance that serves a single organization, raise them as noted.

A refused realtime stream leaves the realtime view without live updates; the dashboard's "Online" count, which polls, is unaffected. The three live-stream settings accept up to 100 000, but above 2 000 they change nothing.

Data retentionCopy Anchor Link

The API applies these at every start: it changes a table's expiry only when the setting differs from what the table has.

BackupsCopy Anchor Link

Read by the backup jobs and the backup CLI when they run, never at start, so a bad value cannot stop the API: Admin → Backups then shows the problem and refuses to start runs, and the CLI exits 2 naming the key. Set them in .env: the CLI, started with docker compose run ... api, reads that file and ignores values exported in the shell. See Backups and restore.

Compose settingsCopy Anchor Link

Read by docker compose from .env (or the shell), not by the API. All are optional.

Sizing advice for these is in Requirements.

SecretsCopy Anchor Link

setup.sh generates these (64 lower-case hex characters each). Compose passes them to the stores and builds the API's connection URLs to Postgres and Valkey from them. The tunnel token is the one secret compose reads from the shell instead.

Set by the compose fileCopy Anchor Link

The api service of docker-compose.yml sets these itself; they win over the env file.

Keeping this page in syncCopy Anchor Link

The tables of API settings on this page are checked against the code by the backend's unit tests (backend/apps/api/src/config/env-docs.test.ts, run by bun run test:unit in backend/): every setting of apps/api/src/config/env.ts must have exactly one row here, with the default the code applies and, for a setting with a closed list of values, a number range or a boolean, the Type the code enforces. The backup settings' defaults are checked against the backup CLI, every variable docker-compose.yml interpolates and every key of .env.example must appear on this page, and Set by the compose file must list exactly the api service's environment: keys. A change to any of them fails the backend's tests until this page follows.