Configuration

How config resolves

Two separate mechanisms, fully disjoint:

• Env vars (table below): read directly at startup. They own all deploy/infra knobs (server, webRtc, limits). None have a config.ini counterpart.
• config.ini (auto-created under the data volume, e.g. ./data/config.ini): file-based config, holds the rate limiters and login lockout only. Missing sections are refilled from defaults and rewritten on every boot, so old configs self-upgrade (no manual migration).

No key lives in both. Set ports, debug, WebRTC and the user cap via env; tune the limiters in config.ini.

---

Operator knobs

Variable	Default	Range / values	What it does
CAESAR_SITE	localhost	hostname, optionally with :port	Public host the instance answers on. Drives Caddy site block + WebAuthn RP ID + allowed origins.
CAESAR_PORT	4991	positive integer	Internal HTTP port the server listens on (behind Caddy).
CAESAR_DEBUG	false in prod, true in dev	boolean	Verbose server logs.
CAESAR_MAX_USERS	0 (unlimited)	non-negative integer	Cap on active (non-deleted) registered users. Bootstrap (first signup) always bypasses. New invites refused at cap; signup refused at cap. UI shows X / Y users on the Invites screen when set.
CAESAR_WEBRTC_WORKERS	1	non-negative integer	Mediasoup worker processes. Each worker binds CAESAR_WEBRTC_PORT + i. Must match the exposed port range in docker-compose.yaml. Primary CPU/concurrency lever.
CAESAR_WEBRTC_PORT	40000	positive integer	Base port for mediasoup workers. Worker N binds base+N.
CAESAR_WEBRTC_ANNOUNCED_ADDRESS	empty (auto)	IP literal	LAN/public IP advertised in ICE candidates. Set only when clients can't reach the host via its default address (e.g. testing from another LAN device against prod-dev).
CAESAR_WEBRTC_MAX_BITRATE	30000000 (30 Mbps)	positive integer (bps)	Per-user transport cap (sum of inbound + outbound across that user's mic/cam/screenshare). Applied via setMaxIncomingBitrate / setMaxOutgoingBitrate.
CAESAR_WEBRTC_LOG_LEVEL	warn in prod, debug in dev	debug, warn, error, none	Mediasoup worker log verbosity.
CAESAR_WEBAUTHN_RPNAME	Caesar	string	2FA hardware keys. Display name shown in browser 2FA prompts.
CAESAR_TRUSTED_PROXY_HOPS	1	non-negative integer	Reverse proxies in front of the app. Client IP (for rate limiting + audit) is the Nth X-Forwarded-For from the right. 1 matches the bundled Caddy; 0 = exposed directly (trust socket peer only).
CAESAR_TRUSTED_CLIENT_IP_HEADER	empty	header name	Single-value real-IP header to trust for CDN setups (e.g. cf-connecting-ip behind Cloudflare). Overrides CAESAR_TRUSTED_PROXY_HOPS. Empty = don't trust such headers (spoofable).

---

Internal / build-time

Avoid touching, unless you know what you doing

Variable	Set by	Purpose
CAESAR_ENV	Dockerfile.prod (= production)	Marks runtime as production. Dev path leaves it unset.
CAESAR_BUILD_VERSION	Docker --build-arg	Burned into the bundle at build time. Surfaced in UI.
MEDIASOUP_WORKER_BIN	dev.sh (host) or Dockerfile (container)	Path to the prebuilt mediasoup worker. Skips the native build.
CAESAR_TLS_DIRECTIVE	docker-compose.yaml (prod-dev profile only)	Injects tls internal into Caddyfile for self-signed :8443.
CAESAR_UPSTREAM	docker-compose.yaml (prod-dev profile only)	Overrides Caddy's reverse proxy target to caesar-prod-dev:4991.

---

Where to set them

• Prod (single instance): write to .env at the repo root. docker-compose.yaml sources it automatically.
• Prod (multi-instance): per-service environment: block in docker-compose.yaml.
• Dev (./dev.sh): export in your shell or prepend the command. MEDIASOUP_WORKER_BIN is auto-set by the script.

---

Rate limiters & login lockout (INI only)

No env overrides. Edit config.ini directly: [rateLimiters.*] (each limiter has maxRequests + windowMs) and [loginLockout] (maxFailures, windowMs, baseLockMs, maxLockMs). Defaults are in apps/server/src/config.ts.