Environment Variables

This is the audited list of every environment variable the Suprnova framework reads at runtime, grouped by the subsystem that consults it. Every entry has been validated against framework source - defaults, types, and behaviour reflect what the code actually does, not what the starter .env happens to ship.

The list also covers the variables the suprnova CLI binary reads (dev server, SSR worker) since those appear in the starter .env and readers will look for them here.

See Configuration for the loading rules (.env → .env.<environment> → process env), the env* helpers (env, env_required, env_optional), and the typed Config::* registration pattern.

Conventions

• Default - the value the framework uses when the variable is unset. none means there is no default; the framework either errors at boot, falls back to a feature default (e.g. Memory driver), or treats the value as None.
• Type - the Rust type the variable is parsed into. bool values accept true/false/1/0/yes/no/on/off (case-insensitive). Out-of-range or unparseable values for typed framework knobs are clamped (workflow), warn!-logged then defaulted (lenient env() / env_optional()), or fail boot (strict try_from_env).
• Required - boot means the framework refuses to start without it in the listed environments. driver means it's required only when the parent driver is selected (e.g. MAIL_SES_REGION is irrelevant unless MAIL_DRIVER=ses). Everything else is optional.

Where a starter .env ships a key the framework never reads (MAIL_FROM_ADDRESS, FILESYSTEM_DISK), it's called out at the end of this chapter.

Application

The APP_* family is the framework's identity and crypto root. These are the variables every Suprnova app sets; the rest of the file becomes relevant as you opt into subsystems.

Two more APP_* variables - APP_LOCALE and APP_FALLBACK_LOCALE - are read by the localization subsystem rather than by AppConfig, so they are listed under Localization below.

Behind a reverse proxy, set APP_TRUSTED_PROXIES

Ignoring proxy headers is the safe default - X-Forwarded-For is caller-supplied and trusting it unconditionally lets anyone claim any address. But the moment a terminating proxy is in front of you (nginx, Traefik, an ALB, Cloudflare), the TCP peer is the proxy, on every request, and leaving this unset does not merely lose the client's address:

• Per-IP rate limits collapse into one bucket. ThrottleRequestsMiddleware's default key is request.ip(), so ThrottleRequestsMiddleware::with(20, 1, "login") stops meaning "20 login attempts per client per minute" and starts meaning 20 in total, across everyone. That is both weaker (no per-attacker budget) and actively dangerous: any single caller can spend the quota and lock every legitimate user out of the login form. See Rate limiting.
• Request::host(), scheme() and port() fall back to the connection rather than to X-Forwarded-Host / -Proto / -Port, so generated absolute URLs can name the internal address and scheme instead of the public one.

List the addresses the proxy hops reach you from - not the client's:

APP_TRUSTED_PROXIES=10.0.0.5,10.0.0.6

Nothing detects this for you: an app behind a proxy with the variable unset looks healthy, serves correctly, and quietly rate-limits everyone as one user.

App-key required matrix

Server

The HTTP listener and request body limits.

Database

Connection URL and sqlx pool tuning. DATABASE_URL is required for any subcommand that touches the database (migrate*, db:sync, db:seed, queue:work with QUEUE_DRIVER=database, workflow:work, the session DB store) and for serve when the app has migrations registered.

Session

Cookie attributes and lifetime for the session subsystem. Note that SESSION_SECURE defaults to true - production-safe by default; flip it off only for local HTTP development.

Localization

The three APP_* variables the localization subsystem reads. Everything else about it - the detection chain, the session key and cookie name it consults, Unicode isolation marks - is code-level configuration on LocalizationConfig, not env. See Localization.

Catalogs themselves are files, not env: lang/<locale>/*.ftl under APP_BASE_PATH. A missing lang/ directory is not an error - the app boots with the framework's embedded English validation catalog.

Cache

Queue

Schedule

Workflow

The #[workflow] long-running stateful worker. All values are clamped to safe minimums rather than honoured blindly - a WORKFLOW_CONCURRENCY=0 would park the worker semaphore forever, so the framework warns and clamps instead of accepting an obviously-broken config.

Mail

MAIL_DRIVER defaults to log - outgoing mail prints to the configured tracing subscriber rather than reaching the network. Flip to memory in tests and smtp/ses/etc. in production. The provider-specific keys/tokens are required only when that driver is selected; an unknown driver value logs a warn! and falls back to log.

SMTP (MAIL_DRIVER=smtp)

Postmark (MAIL_DRIVER=postmark)

Amazon SES (MAIL_DRIVER=ses)

SendGrid (MAIL_DRIVER=sendgrid)

Mailgun (MAIL_DRIVER=mailgun)

Resend (MAIL_DRIVER=resend)

Rate Limiting

Hashing

Password-hashing driver and per-algorithm parameters. Invalid values return a FrameworkError::param at first hash, surfacing misconfiguration immediately instead of silently defaulting.

Auth Flows

Two-factor authentication uses APP_NAME (covered under Application) as the TOTP issuer string - there is no dedicated 2FA_ISSUER env var. The issuer falls back to "Suprnova" when APP_NAME is unset.

Inertia / Frontend

Maintenance Mode

Events

Logging

LOG_FORMAT is environment-aware: in production (APP_ENV=production) the default is json for log-aggregator friendliness; everywhere else the default is pretty for human-readable local/dev output. An explicit value always wins.

Observability (OpenTelemetry)

CLI / dev server

These are read by the suprnova CLI binary (dev server, SSR worker) rather than the runtime framework - they appear in the starter .env or are honoured by suprnova serve / suprnova ssr:*.

Subsystems with no env vars

A few subsystems are configured entirely in Rust code via the container or service registration - they have zero env vars the framework reads:

• Filesystem / Storage. Disks are registered with FilesystemRegistry::add_disk(name, driver) in bootstrap(). There is no FILESYSTEM_DISK env var (the name appears in some starter .env files but is not consulted by the framework - see "Variables the framework does not read" below).
• Broadcasting & WebSockets. Channels are registered with the ws!() macro and BroadcastHub configuration in code. The driver itself rides on whatever the configured CACHE_DRIVER selects.
• CORS, CSRF, Idempotency, Timeout. Configured via builder structs passed to the middleware constructors in bootstrap(). The defaults are conservative enough that a typical app never touches them.
• OAuth (torii integration). Provider client IDs and secrets (GITHUB_CLIENT_ID, GOOGLE_CLIENT_ID, etc.) are user configuration - your bootstrap() reads them via std::env::var(...) and passes them to torii::Plugin::new(...). The framework itself doesn't read them.
• Vector search, Notifications, Payments, Feature Flags. Each registers concrete drivers via App::bind in bootstrap(). Pick your driver in Rust; pass any URLs/keys it needs as your own env vars.

Variables the framework does not read

The scaffolded starter .env lists a few keys for human-author convenience that the framework never consults. They're documented here so a reader searching for them isn't left wondering:

• MAIL_FROM_ADDRESS - a Laravel-style placeholder the framework never consults. The actual from-address the auth-flow facades use is MAIL_FROM (covered under Mail). Your own Mailable types can read it via env_optional if you want to keep the Laravel name, but nothing in suprnova::* does. (MAIL_FROM_NAME is read as of 0.5.9 - see the Mail chapter - so it's no longer listed here.)
• FILESYSTEM_DISK - placeholder for the default disk name. Set the default in code via FilesystemRegistry::set_default(name) instead.

How values are parsed

A short reference for the three env-helper variants - see Configuration for the full treatment:

Strict variants (AppConfig::try_from_env, ServerConfig::try_from_env) are what Config::init calls, so a typo in APP_DEBUG=tru or SERVER_PORT=80a0 aborts boot with a structured error instead of silently reverting to the default. Lenient variants exist for the broader call-site population (including impl Default) where a parse failure must not panic.

Per-environment overrides

The loader reads files in this order, each overriding the previous:

1. .env
2. .env.<environment> (e.g. .env.production, .env.staging, .env.testing, .env.<custom> for APP_ENV=<custom>)
3. Process environment

That means a containerised production deploy can ship a minimal .env.production overriding only the keys that differ from .env (driver names, URLs, key material), and the real container env overrides both for secrets that should never land in a committed file.

See Configuration for the exact loader behaviour and the LOADED_KEYS tracking that prevents stale .env values from promoting into the "real system env" tier across reloads.

Next

• Configuration - typed Config::* registration, the env* helpers, environment detection
• Deployment - what to set in production
• Encryption - APP_KEY rotation via APP_KEY_PREVIOUS
• Application Bootstrap - where env-driven boot order is established