Configuration Reference

Configuration Reference

ggscale reads its configuration from environment variables. This page groups the ones you set most often, with defaults. The complete, drift-tested list lives in .env.example at the repository root, which is the source of truth; every variable the server reads appears there.

Any secret variable also accepts a <NAME>_FILE form that reads the value from a file, so you can mount a secret instead of passing it in the environment. A variable set to an empty string counts as unset.

Core

Variable	Default	Purpose
ENV	dev	Set to production to require the hardening config below.
HTTP_ADDR	:8080	Address the HTTP server binds.
APP_REGION	local	Region label for realtime caps. Must be explicit in production.
LOG_LEVEL	info	Log verbosity.
HTTP_REQUEST_TIMEOUT	15s	Per-request deadline before 503 + Retry-After.

Database

Variable	Default	Purpose
DATABASE_URL	required	App login DSN. Supports _FILE.
DB_MIGRATE_URL	falls back to DATABASE_URL outside prod	Elevated DSN for startup migrations. Required in production and must differ from DATABASE_URL.
MIGRATIONS_DIR	/migrations	Directory the server reads SQL migrations from on startup.
DB_MAX_CONNS / DB_MIN_CONNS	25 / 2	pgx pool bounds.
DB_READ_URL	empty	Optional read-replica DSN for read-heavy GETs.

Secrets

Outside production, an empty value here is generated into the server_secrets table on first boot. In production the server requires the marked ones.

Variable	Purpose
JWT_SIGNING_KEY	Signs player session tokens. Required in production.
EMAIL_VERIFY_SIGNING_KEY	32-byte hex key for verification cookies. Required in production.
TWO_FACTOR_ENC_KEY	Optional 32-byte hex key that encrypts TOTP secrets at rest. Auto-generated when empty.
METRICS_AUTH_TOKEN	Bearer token gating /metrics (>= 32 chars). Required in production unless METRICS_AUTH_DISABLED=true.

Control panel

Variable	Default	Purpose
CONTROL_PANEL_DISABLED	false	Unmount /v1/control-panel when true.
CONTROL_PANEL_BASE_URL	empty	External origin for invite links. Required (https://) in production.
CONTROL_PANEL_COOKIE_SECURE	false	Must be true in production.
CONTROL_PANEL_BOOTSTRAP_TOKEN_FILE	empty	Writes the first-run token to a file. Required in production.

Email

Variable	Default	Purpose
MAIL_PROVIDER	smtp	smtp or noop.
SMTP_ADDR	localhost:1025	SMTP server host:port. Default matches dev Mailpit.
SMTP_USER / SMTP_PASSWORD	empty	Credentials for authenticated relays.
SMTP_TLS	starttls	off, starttls, or implicit.
MAIL_FROM	noreply@ggscale.dev	From address on outbound mail.

Network and CORS

Variable	Default	Purpose
CORS_ALLOWED_ORIGINS	empty (* in dev)	Allowed origins. Required and no * in production.
TRUSTED_PROXY_HEADER	empty	Forwarded-IP header to honor behind a proxy.
TRUSTED_PROXY_CIDRS	empty	Networks allowed to set that header.

Relay (P2P TURN)

Off unless FEATURE_P2P_RELAY_ENABLED=true with a shared secret. See P2P Connectivity and TURN Relay.

Variable	Default	Purpose
FEATURE_P2P_RELAY_ENABLED	false	Relay kill switch.
RELAY_SHARED_SECRET	empty	TURN-REST signing secret (>= 32 bytes). Supports _FILE.
RELAY_URLS	empty	Comma-separated turn:/turns: URIs clients dial. Required when the issuer is on.
RELAY_STUN_URLS	empty	Optional stun:/stuns: URIs.
RELAY_PUBLIC_IP / RELAY_UDP_PORT	`` / 3478	Relay listener address.

Fleet (beta)

Off unless FEATURE_FLEET_ENABLED=true. See Game Server Fleet.

Variable	Default	Purpose
FEATURE_FLEET_ENABLED	false	Fleet kill switch.
FLEET_BACKEND	empty	agones or plugin:<name>.
FLEET_REGION	local	Region label on allocations.
FLEET_PLUGIN_DIR	/etc/ggscale/plugins	Directory scanned for plugin binaries.

Quotas and entitlements

Variable	Default	Purpose
QUOTAS_ENFORCE_NEW_TENANTS	false	New tenants start quota-enforced when true. Self-host default leaves them uncapped.
ENTITLEMENT_API_ENABLED	false	Mount the private entitlement API for an external billing service.

For everything else, including matchmaker tuning, connection caps, Agones and k3s auth, and billing link-out, read .env.example.