Environment Variables & .env Cascade#

The .env family of files is loaded with the standard cascade of symfony/dotenv.

Load order (priority)#

.env — committed defaults
.env.local — local override (gitignored)
.env.{APP_ENV} — environment-specific defaults (committed)
.env.{APP_ENV}.local — environment-specific local override (gitignored)

A nonexistent file is silently skipped.
A value already in $_ENV / $_SERVER / getenv() (a real environment variable) takes precedence over all of these files, .local included. Among the files, .local overrides the committed versions.

Do not write secrets in .env. .env is normally committed. Put auth tokens etc. in the gitignored .env.local.

Example .env:

DATABASE_DSN=mysql:host=127.0.0.1;dbname=app;charset=utf8mb4
DATABASE_USER=app
DATABASE_PASSWORD=secret

The committed .env does not set APP_ENV. Without APP_ENV the app is treated as production, so a deploy that forgets it never runs in dev mode. Enable dev mode per machine in the gitignored .env.local. relayer init writes .env.local only into a new project, so after cloning run:

echo APP_ENV=dev >> .env.local

Available environment variables#

Variable	Use
`APP_ENV`	`dev`/`development` enables PSX on-the-fly compilation + profiler. Any other value, or none, is treated as production. For development, set `APP_ENV=dev` in the gitignored `.env.local`
`DATABASE_DSN`	PDO connection string. If unset, the Db layer is not registered
`DATABASE_USER`	DB username
`DATABASE_PASSWORD`	DB password
`DATABASE_TIMEOUT`	Connection timeout in seconds (`PDO::ATTR_TIMEOUT`)
`DATABASE_READ_TIMEOUT`	MySQL read timeout in seconds (optional)
`PROFILER_EXCLUDED_PATHS`	Profiler-excluded paths (comma-separated, prefix match)
`HTTP_CLIENT_TIMEOUT`	HTTP client overall request timeout in seconds (optional)
`HTTP_CLIENT_CONNECT_TIMEOUT`	HTTP client connection-establishment timeout in seconds (optional)
`LOG_LEVEL`	Logger threshold. One of the 8 PSR-3 levels (default dev=`debug`/production=`info`; a misspelling soft-fails to the default)
`LOG_FILE`	Logger output path (STDERR if unset)
`APP_LOCALE`	Internationalization default/active locale (default `en`)
`APP_LOCALES`	Supported locales (comma-separated. Default is `APP_LOCALE` only. Two or more enable locale switching)
`LOCALE_COOKIE`	Cookie name that carries the locale (default `locale`. CDN-safe, no session needed)
`LOCALE_PATH_PREFIX`	Opt-out of `/{locale}/...` routing (default `true`)
`NATIVE_ROUTE_TIMEOUT`	Timeout in seconds for native routes (default 30)
`GO_BIN`	Path to the `go` that `relayer native:build` uses
`ORIGIN_SECRET` / `ORIGIN_SECRET_PREVIOUS`	The secret that enables OriginGuard, and the old value during rotation
`ORIGIN_GUARD_HEADER` / `ORIGIN_GUARD_EXCEPT` / `ORIGIN_GUARD_MODE`	OriginGuard's header name (default `X-Origin-Secret`), excluded paths, `enforce` / `report`
`TRUSTED_PROXIES` / `TRUSTED_PROXY_PRESET` / `CLOUDFLARE_IP_RANGES`	CIDRs that enable TrustedProxy, `fly` / `cloudflare` / `xff`, and the IP ranges of a Cloudflare layer
`TYPESAFE_API_KEY` / `TYPESAFE_MODEL`	API key and model (default `jev-latest`) that enable the Judge for `satisfies()`

DATABASE_* are optional, and the Db layer is registered in the DI container only when DATABASE_DSN is set (see Database).

APP_LOCALE / APP_LOCALES / LOCALE_COOKIE / LOCALE_PATH_PREFIX are also optional; if you set none of them it stays single-locale (English) at no cost (see Internationalization).

Variables specific to this site#

The above are framework (relayer) variables. This documentation site (relayer-doc) itself additionally reads the article store's TURSO_DATABASE_URL / TURSO_AUTH_TOKEN (var/docs.db if unset) and the following. All are set as Fly secrets.

Variable	Use
`GA_MEASUREMENT_ID`	GA4 measurement ID (only the `G-XXXXXXXXXX` form is accepted). Only when set does it emit gtag.js in the production `<head>`. If unset, it emits nothing = dev/local has no measurement

See Deployment for details.