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 (the dev server) 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), 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.

A proxy that serves the application under a path, such as /billing, names that path in X-Forwarded-Prefix, which counts under the same rule. See Serving under a path prefix.

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.

Laravel database

Variables for an application on a database a Laravel application created. See Running on a Laravel Database.

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

An upgraded deployment with CACHE_DRIVER=redis finds its cache empty: the store used to read REDIS_PREFIX, suprnova_cache: by default, as its cache prefix on the database REDIS_URL names, and now runs on the cache connection's database under REDIS_PREFIX and CACHE_PREFIX. Set REDIS_CACHE_CONNECTION=default, an empty REDIS_PREFIX and CACHE_PREFIX=suprnova_cache: (or your old REDIS_PREFIX) to keep the old keys. See Cache. | REDIS_COMMAND_RETRIES | 0 | u32 | Extra retries for read-shaped Redis commands, on top of the one every read already gets. Applies to the cache, queue, and rate-limit drivers, and to the reads of the Redis facade. Writes never retry at any value. Budget it in seconds: a retry against a dropped connection waits for the reconnect, so it costs the driver's whole connect and response budget - up to 3 connect retries at most 500 ms apart, each capped at 2 s, plus a 5 s response timeout on the cache driver; up to 6 connect retries with an uncapped exponential delay, each capped at 1 s, plus a 500 ms response timeout on the queue and rate-limit drivers. The clamp of 10 bounds attempts, not seconds: at that setting one read makes 12 attempts. A timeout counts as transient too, so during a stall each wrapped read issues up to that many commands. An unparseable value falls back to 0. |

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)

Web Push

Rate Limiting

Filesystem

You set S3_BUCKET or AWS_BUCKET to register an S3 disk named s3 at boot, 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 both bucket names unset, you register no environment disk. 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, except the disk name FILESYSTEM_DISK gives.

FILESYSTEM_DISK names the default disk that Storage::default_disk() returns; Storage::set_default_disk in code wins over it. With neither setting, you use the registered local disk, or get an error naming local and FILESYSTEM_DISK. When it names a disk that is not registered once the bootstrap has run, boot fails. The console binary boots no driver of the environment. A command that uses the s3 disk calls suprnova::filesystem::bootstrap_from_env() at the end of its own bootstrap, after it registers its disks, because that call checks the default disk too. 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, the decode limits that bound hostile input, and orientation on decode. 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

Live

Every limit Live runs under is one of these keys. The server's configuration is the only source: the bootstrap writes each value into the page, and the browser runtime applies the value it reads there, never a smaller one of its own. Values are plain whole numbers, with bytes written out (16777216, not 16MiB). Config::init reads every key at boot, so a value that is not a whole number, or that breaks its rule, fails boot with the key, the value and the rule in the message. LiveConfig::builder() sets the same limits in code; see Live.

Maintenance Mode

Events

Logging

LOG_FORMAT is environment-aware: in production (APP_ENV=production, or APP_ENV unset) 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.

You set the syslog channel's ident with APP_NAME. If you leave it unset or empty, the ident is suprnova.

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.

Heap profiling

CLI / dev server

These are read by the suprnova CLI binary's dev server rather than the runtime framework - they appear in the starter .env or are honoured by suprnova serve. The CLI's ssr:* commands read none of their own: they run the application binary's commands, which read the Inertia configuration the application installed (see Console).

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")), or reached as the default disk FILESYSTEM_DISK names (Storage::default_disk()). 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. The exceptions are the table-layout variables in Laravel database above and WEB_PUSH_ENDPOINT_ORIGINS in Web Push.
• 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.)

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.local
3. .env.<environment> (e.g. .env.production, .env.staging, .env.testing, .env.<custom> for APP_ENV=<custom>), then .env.<environment>.local, only when APP_ENV is set, in the process or in .env
4. 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