Environment Variables

bext reads environment variables at startup. They override values set in bext.config.toml, giving you a clean way to inject secrets and per-environment configuration without modifying config files.

Precedence

Configuration values are resolved in this order (highest priority first):

1. CLI flags (--listen, --log-level, --workers) 2. Environment variables (BEXT_LISTEN, BEXT_LOG_LEVEL) 3. Config file (bext.config.toml) 4. Defaults (built into the binary)

This means an environment variable always overrides the config file, and a CLI flag overrides both.

Variable Reference

Server

Variable	Description	Default	Example
`BEXT_CONFIG`	Path to the config file	`bext.config.toml`	`/etc/bext/bext.config.toml`
`BEXT_LISTEN`	Listen address (host:port)	`0.0.0.0:3061`	`127.0.0.1:8080`
`PORT`	Listen port (shorthand, overridden by `BEXT_LISTEN` if both set)	`3061`	`3000`
`BEXT_WORKERS`	Number of Actix worker threads (0 = auto)	`0`	`8`
`BEXT_STATIC_DIR`	Path to static assets directory	`./dist/static`	`/var/www/static`
`BEXT_UPSTREAM`	Upstream server URL for reverse proxy mode	(none)	`http://127.0.0.1:3001`
`BEXT_MAX_BODY_SIZE_MB`	Maximum request body size in megabytes	`10`	`50`

Logging

Variable	Description	Default	Example
`BEXT_LOG_LEVEL`	Log level filter	`info`	`debug`
`RUST_LOG`	Fine-grained log filter (standard Rust format)	`info,bext_server=debug`	`warn,bext_core=trace`
`BEXT_LOG_FORMAT`	Log output format	`json`	`pretty`
`BEXT_LOG_FILE`	Log file path (when output is `file`)	(none)	`/var/log/bext/bext.log`

TLS

Variable	Description	Default	Example
`BEXT_TLS_CERT`	Path to TLS certificate file (PEM)	(none)	`/etc/ssl/certs/domain.pem`
`BEXT_TLS_KEY`	Path to TLS private key file (PEM)	(none)	`/etc/ssl/private/domain.key`
`BEXT_TLS_AUTO_ACME`	Enable automatic Let's Encrypt certificates	`false`	`true`
`BEXT_ACME_EMAIL`	Email for ACME account registration	(none)	`admin@example.com`
`BEXT_ACME_DIR`	Directory to store ACME certificates	`/var/lib/bext/certs`	`/etc/bext/certs`

Rendering / SSR

Variable	Description	Default	Example
`BEXT_BUNDLE_PATH`	Path to the SSR bundle	`dist/ssr-bundle.js`	`/app/dist/server/index.js`
`BEXT_RENDER_WORKERS`	Number of V8 SSR worker isolates	`4`	`8`
`BEXT_RENDER_TIMEOUT_MS`	SSR render timeout in milliseconds	`10000`	`15000`
`BEXT_WORKER_MEMORY_LIMIT_MB`	Memory limit per render worker	`256`	`512`

Cache

Variable	Description	Default	Example
`BEXT_CACHE_MAX_ENTRIES`	Maximum ISR cache entries	`10000`	`50000`
`BEXT_CACHE_TTL_MS`	Default ISR cache TTL in milliseconds	`60000`	`300000`
`BEXT_CACHE_SWR_MS`	Default stale-while-revalidate window	`3600000`	`86400000`

Redis

Variable	Description	Default	Example
`REDIS_URL`	Redis connection URL for L2 cache and distributed features	(none)	`redis://redis.internal:6379/0`
`BEXT_REDIS_POOL_SIZE`	Redis connection pool size	`16`	`32`

Database

Variable	Description	Default	Example
`DATABASE_URL`	PostgreSQL connection URL	(none)	`postgres://user:pass@db:5432/bext`
`BEXT_DB_POOL_SIZE`	Database connection pool size	`10`	`25`

License

Variable	Description	Default	Example
`BEXT_LICENSE_KEY`	License key for Pro or Enterprise features	(none)	`BEXT-PRO-eyJ0aWVy...`

Admin

Variable	Description	Default	Example
`BEXT_ADMIN_SECRET`	Secret token for the admin API (`/__bext/admin/`)	(none, admin disabled)	`s3cret-admin-t0ken`
`BEXT_JWT_SECRET`	JWT signing secret for auth middleware	(none)	`my-jwt-secret-256bit`

Telemetry

Variable	Description	Default	Example
`BEXT_OTLP_ENDPOINT`	OpenTelemetry OTLP collector endpoint (Pro)	(none)	`http://otel:4317`
`BEXT_OTLP_PROTOCOL`	OTLP protocol	`grpc`	`http`
`BEXT_OTLP_SAMPLE_RATE`	Trace sampling rate (0.0 to 1.0)	`0.1`	`1.0`

Plugin System

Variable	Description	Default	Example
`BEXT_PLUGIN_DIR`	Directory to scan for plugins	`plugins/`	`/etc/bext/plugins`
`BEXT_PLUGIN_TIMEOUT_MS`	Plugin execution timeout	`5000`	`10000`
`BEXT_WASM_MEMORY_MB`	Memory limit per WASM plugin	`64`	`128`

Storage & Backups

Variable	Description	Default	Example
`BEXT_STORAGE_PROVIDER`	Object storage backend	`local`	`s3`, `r2`
`BEXT_STORAGE_BUCKET`	S3/R2 bucket name	(none)	`my-bext-backups`
`BEXT_STORAGE_REGION`	AWS region (ignored for R2)	`us-east-1`	`eu-west-1`
`BEXT_STORAGE_ENDPOINT`	Custom endpoint (required for R2/MinIO)	(none)	`https://ACCT.r2.cloudflarestorage.com`
`BEXT_STORAGE_ACCESS_KEY`	S3/R2 access key	(none)	`AKIA...`
`BEXT_STORAGE_SECRET_KEY`	S3/R2 secret key	(none)	`wJalr...`

Cloud Sync (nginx)

Variable	Description	Default	Example
`BEXT_CLOUD_URL`	bext cloud API URL	`http://localhost:3025`	`https://cloud.bext.dev`
`BEXT_CLOUD_API_KEY`	API key for CLI-to-cloud auth	(none)	`my-secret-key`

Miscellaneous

Variable	Description	Default	Example
`DOTENV_PATH`	Path to `.env` file	`.env`	`/etc/bext/.env.production`
`BEXT_UPGRADE_FDS`	Socket FDs for zero-downtime upgrade (set automatically)	(none)	`3,4`
`BEXT_UPGRADE_OLD_PID`	Old process PID during upgrade (set automatically)	(none)	`12345`
`NODE_ENV`	Passed through to SSR bundles and plugins	`production`	`development`

Using `.env` Files

bext automatically loads a .env file from the working directory at startup:

# .env
BEXT_LICENSE_KEY=BEXT-PRO-eyJ0aWVy...
DATABASE_URL=postgres://user:pass@db:5432/bext
REDIS_URL=redis://localhost:6379/0
BEXT_ADMIN_SECRET=s3cret-admin-t0ken

Override the .env file path:

DOTENV_PATH=/etc/bext/.env.production bext-server run

Variables in .env do not override existing OS environment variables. This means you can set secrets in the OS environment and use .env only for non-sensitive defaults.

Security Notes

- Never commit .env files containing secrets to version control. Add .env to your .gitignore.

- Prefer BEXT_LICENSE_KEY as an environment variable over putting the key in bext.config.toml, especially in containerized environments.

- The BEXT_ADMIN_SECRET must be set to enable the admin dashboard. Without it, the admin endpoints return 404.

- For Kubernetes, use Secrets or an external secret manager (Vault, AWS Secrets Manager) to inject sensitive variables.