Environment variables

Railbase is configured by flags, environment variables, optional .env / railbase.yaml files, and built-in defaults, in that precedence order (flag > env > .env file > railbase.yaml > default). This page lists the variables an operator typically sets; for the matching flags see the CLI reference.

Core server

Variable	Default	Purpose
RAILBASE_HTTP_ADDR	:8095	HTTP listen address
RAILBASE_HTTP_AUTOPORT	false	On a bind conflict (port busy, or a listener on another address family shares the port), advance to the next free port instead of failing — for CI / dev harnesses that must not wedge on a stale listener
RAILBASE_DATA_DIR	<binary-dir>/pb_data	Data directory (falls back to ./pb_data when the binary's own dir isn't writable)
RAILBASE_HOOKS_DIR	./pb_hooks	Where *.pb.js hooks load from
RAILBASE_PROD	false	Production mode (disables dev conveniences)
RAILBASE_DEV	false	Explicit development vault fallback; never set in production
RAILBASE_LOG_LEVEL	warn	debug · info · warn · error
RAILBASE_LOG_FORMAT	json	text or json
RAILBASE_SHUTDOWN_GRACE	15s	Graceful-shutdown timeout

Vault (data & encryption)

Variable	Default	Purpose
RAILBASE_VAULT_PATH	<data-dir>/railbase.vault	Vault file location
RAILBASE_VAULT_PASSWORD	—	Unlock password (required in production)
RAILBASE_VAULT_PASSWORD_FILE	—	File holding the password (preferred for systemd / secrets)
RAILBASE_VAULT_CACHE_MB	1024	Vault page-cache size, MB
RAILBASE_BACKUPS_DIR	<data-dir>/backups	Where snapshots are written
RAILBASE_ENCRYPT_STORAGE	false	Encrypt uploaded files at rest
RAILBASE_STORAGE_DIR	<data-dir>/storage	Uploaded-file storage directory
RAILBASE_STORAGE	—	Filesystem storage alias (fs:/path or bare path); S3/GCS/Azure drivers are not shipped yet
RAILBASE_STORAGE_MAX_UPLOAD_BYTES	52428800	Maximum upload size for file endpoints
RAILBASE_STORAGE_URL_TTL	5m	Signed file URL lifetime

Marketplace, licensing & static assets

Variable	Default	Purpose
RAILBASE_PLUGIN_MANAGER	(on)	The marketplace / plugin manager is built in and enabled by default. Set to 0 to disable it.
RAILBASE_MARKETPLACE_URL	railbase.app	Marketplace base URL override for staging/dev; production should use the vendor default
RAILBASE_LICENSE_GRACE_DAYS	14	Days after license expiry before a paid plugin goes dormant (0 disables grace)
RAILBASE_PLUGIN_KEY	derived	32-byte base64 override for plugin-bundle encryption at rest; normally leave unset
RAILBASE_SUPERVISOR	(on where supported)	Enables supervised self-update / re-exec path; set 0 for fallback mode
RAILBASE_PUBLIC_DIR	(empty)	Directory of static assets to serve at / (empty disables)

Networking & access

Variable	Purpose
RAILBASE_SITE_NAME / RAILBASE_SITE_URL	Public site identity and URL used in links and admin surfaces (feed the site.name / site.url settings)
RAILBASE_PUBLIC_URL	The env fallback WebAuthn derivation and email templates actually read when the site.url setting is unset
RAILBASE_TRUSTED_PROXIES	CIDR list whose X-Forwarded-For is trusted (set this behind a proxy)
RAILBASE_ALLOW_IPS / RAILBASE_DENY_IPS	CIDR allow / deny filters
RAILBASE_EGRESS_ALLOW	Allowlist of exceptions to the outbound SSRF guard on plugin HTTP ($app.http.fetch) — comma-separated CIDRs/IPs, optionally plugin-scoped as slug=CIDR
RAILBASE_CORS_ALLOWED_ORIGINS	Permitted browser origins
RAILBASE_CORS_ALLOW_CREDENTIALS	Allow credentialed cross-origin browser calls (requires exact origins)
RAILBASE_RATE_LIMIT_PER_IP / RAILBASE_RATE_LIMIT_PER_USER / RAILBASE_RATE_LIMIT_PER_TENANT	Optional rate-limit rules such as 60/m
RAILBASE_ANTIBOT_ENABLED	Honeypot / user-agent sanity checks on auth and OAuth paths
RAILBASE_ADMIN_URL	Base URL used in admin/bootstrap emails

Tenancy, compatibility & logs

Variable	Purpose
RAILBASE_TENANCY_MULTI_TENANT	Enables row-level multi-tenant mode and frontend tenant switching support
RAILBASE_TENANCY_ALLOW_SWITCH	Lets app users switch between tenants they belong to
RAILBASE_TENANCY_IMPLICIT_SINGLE_TENANT	When on (default), a header-less request resolves into the sole tenant if exactly one exists
RAILBASE_COMPAT_MODE	Runtime compatibility mode (strict, native, both); /v1 is still reserved, so build against /api
RAILBASE_LOGS_PERSIST	Persist structured application logs into the admin log browser

RAILBASE_PB_COMPAT and RAILBASE_PBCOMPAT are legacy compatibility fallbacks that still read when no compat.mode setting is saved. Prefer RAILBASE_COMPAT_MODE or railbase config set compat.mode ... for new deployments.

Mail, auth & enterprise identity

Variable	Purpose
RAILBASE_MAILER_DRIVER	console, smtp, or ses
RAILBASE_MAILER_FROM / RAILBASE_MAILER_FROM_NAME	Default sender identity
RAILBASE_MAILER_SMTP_HOST / PORT / USER / PASS / TLS	SMTP delivery settings
RAILBASE_MAILER_SES_REGION / ACCESS_KEY_ID / SECRET_ACCESS_KEY / ENDPOINT	SES delivery settings
RAILBASE_MAILER_RL_GLOBAL / RAILBASE_MAILER_RL_RECIPIENT	Mail send rate limits
RAILBASE_OAUTH_<PROVIDER>_<FIELD>	OAuth provider fallback settings, e.g. Google/GitHub client id and secret. For generic OIDC, RAILBASE_OAUTH_OIDC_ISSUER + _CLIENT_ID / _CLIENT_SECRET drive discovery
RAILBASE_WEBAUTHN_RP_ID / RP_NAME / ORIGIN / ORIGINS	Passkey/WebAuthn relying-party settings
RAILBASE_SESSION_TTL	User-session sliding lifetime (a Go duration like 8h); each request renews it. Unset = the built-in 8h. Also settable in Settings → Authentication
RAILBASE_SESSION_HARD_CAP	Absolute maximum a user session may live from creation, regardless of renewal (e.g. 720h). Unset = the built-in 30 days. Also in Settings → Authentication

LDAP and SAML are configured through admin/settings keys (auth.ldap.*, auth.saml.*) rather than public env fallbacks.

Operations & observability

Variable	Purpose
RAILBASE_ENABLE_UI_RESTORE	Enables the guarded in-admin restore capability; CLI restore is always available with file lock
RAILBASE_METRICS_PROMETHEUS_ENABLED / RAILBASE_METRICS_TOKEN	Prometheus metrics endpoint toggle and bearer token
RAILBASE_OTLP_ENDPOINT / RAILBASE_OTLP_HEADERS / RAILBASE_OTLP_SERVICE_NAME / RAILBASE_OTLP_INTERVAL_S	OTLP metrics export
RAILBASE_AUDIT_ARCHIVE_TARGET	Audit archive target; S3 settings use the RAILBASE_AUDIT_S3_* prefix
RAILBASE_AUDIT_SEAL_SIGNER	Selects the audit-seal signer (local default, or kms); only when set to kms are the RAILBASE_AUDIT_KMS_KEY_ID / _REGION / _ENDPOINT values read

A production starting point

RAILBASE_PROD=true
RAILBASE_HTTP_ADDR=:8095
RAILBASE_DATA_DIR=/var/lib/railbase
RAILBASE_VAULT_PASSWORD_FILE=/run/secrets/railbase-vault
RAILBASE_TRUSTED_PROXIES=127.0.0.1/32
RAILBASE_LOG_FORMAT=json
RAILBASE_ENCRYPT_STORAGE=true

This page lists public operator knobs, not test-only or development seam variables. Run railbase config list to see the live settings on your instance.