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::with(...) keys on request.ip() and the request path, so ThrottleRequestsMiddleware::with(20, 1, "login") stops meaning "20 login attempts per client per minute" and starts meaning 20 in total, across everyone. ThrottleRequestsMiddleware::default() keys on the user id when a user is signed in and on request.ip() otherwise, so it collapses the same way for every visitor who is not signed in. 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. An entry is one address or a range in CIDR form:

APP_TRUSTED_PROXIES=10.0.0.5,173.245.48.0/20,2400:cb00::/32

Four rules decide how the list is used:

• List every proxy of the chain, not the last one alone. Request::ip() reads X-Forwarded-For from the right and returns the first address that is not in the list. A proxy that is not listed is taken for the client, and all of its clients share one address. This includes an address that a load balancer adds behind the client's, as the external Application Load Balancer of Google Cloud does.
• A range must hold proxies and nothing else. A client that connects from a trusted address is believed like a proxy: it writes its own X-Forwarded-For, and with it the address ip() returns, and the forwarded host and scheme as well. The network of the pods of a cluster and the range of a VPN have clients in them. Do not list them.
• The proxy must write X-Forwarded-For itself, by adding the address it saw to the header or by replacing the header. A proxy that passes the client's header on as it came lets the client write all of it.
• X-Real-IP is read only when the request has no X-Forwarded-For at all. A proxy that writes X-Real-IP alone must remove the client's X-Forwarded-For. The Forwarded header of RFC 7239 is not read.

An IPv4 address written as an IPv6 one (::ffff:10.0.0.5) counts as the IPv4 address, in the headers and for the peer. Request::ips() returns the whole chain. It is a record, not something to decide by.

Nothing detects a missing list 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. The five liveness knobs are how you survive a network that drops idle connections - see Pool liveness.

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, file for .eml previews you can open in a mail client, 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.

File (MAIL_DRIVER=file)

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

Filesystem

When S3_BUCKET is set, the server registers an S3 disk named s3 as it boots, beside the queue, the rate limiter and the mail transport. The variables work for AWS S3 and for S3-compatible services (MinIO, RustFS, R2, B2). With S3_BUCKET unset, nothing is registered. A disk that your bootstrap() registered under the name s3 is kept as it is, and the variables are not read then.

Blank values count as unset. No error repeats the value of a variable.

There is no default disk. Every call names the disk it uses, so FILESYSTEM_DISK is not read. The console binary boots no driver of the environment. A command that uses the s3 disk calls suprnova::filesystem::bootstrap_from_env() in its own bootstrap. To register the same configuration under a name of your own, use S3Config::from_env(). See Filesystem.

Vector search

The three vector drivers read their connection from the environment when you call their from_env() constructor. Nothing reads these variables at boot. You choose the driver in Rust and register it in bootstrap(). See Vector.

A missing variable is named in the error at boot, and the error never shows a URL, because a URL carries the password.

Images

Image driver selection and the decode limits that bound hostile input. Out-of-range limits clamp with a warn! rather than failing boot: a limit of zero would reject every image in the application. An unknown IMAGE_DRIVER fails at first use, naming the valid values.

See Images for the two-tier limit enforcement and how to choose between the drivers.

Hashing

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

Validation

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)

An endpoint must be a URL with the scheme http or https and a host. A signal whose endpoint is not one, such as a path alone, is left out and reported in the log, and the other signals are still exported. The report never repeats the endpoint, which can carry a password or a token. The exporters need the otel cargo feature. The other standard OTLP variables (OTEL_EXPORTER_OTLP_HEADERS, _PROTOCOL, _TIMEOUT) are read by the OpenTelemetry exporter directly.

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, apart from S3. Disks are registered by name with Storage::register_* in bootstrap() and addressed by name at the call site (Storage::disk("public")). There is no default disk, so there is no FILESYSTEM_DISK env var (see "Variables the framework does not read" below). The one exception is the S3-compatible s3 disk, which the S3_* variables configure (see Filesystem above and Docker).
• 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.
• Magnetar and OAuth. MagnetarConfig is built in application bootstrap. The API starter reads PASSKEY_RP_ID and PASSKEY_RP_ORIGIN, but the framework itself does not. OAuth provider IDs, secrets, callback URLs, scopes, transports, and policy values are supplied programmatically through the Magnetar provider registry. Applications may source those values from environment variables or a secret manager.
• 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.
• Vector search registers its drivers the same way. The Qdrant, MariaDB and Pinecone drivers have a from_env() constructor that reads the variables in Vector search above.

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 - Laravel's default disk name. Suprnova has no default disk: every call names the disk it uses (Storage::disk("s3")).

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 tracking of loaded keys 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