Environment variables¶

Advanced reference for headless / container configuration. Most day-to-day tunables live in the Settings UI (SQLite). Env vars wire the process, supply secrets at bootstrap, and act as fallbacks when a UI value is empty.

Precedence for fallbacks: saved Settings value wins over env, which wins over built-in default (unless noted).

Container / entrypoint¶

Variable	Default	Effect
`CONFIG_PATH`	`/config`	SQLite, blobs, backups, session key
`PUID` / `PGID`	`1000`	Container user/group for `/config` ownership
`TZ`	unset	Schedules and log timestamps
`BACKEND_URL`	`http://localhost:8080`	Frontend → backend (set by entrypoint if empty)
`FRONTEND_BACKEND_API_KEY`	random if unset	Shared API key; also seeds `api.key` when empty
`MAX_BACKEND_HEALTH_RETRIES`	`30`	Entrypoint health wait
`MAX_BACKEND_HEALTH_RETRY_DELAY`	`1`	Seconds between health probes

Frontend (Node)¶

Variable	Default	Effect
`PORT`	`3000`	HTTP listen port
`BACKEND_URL`	required in split deploys	Backend base URL
`FRONTEND_BACKEND_API_KEY`	required	Injected as `x-api-key` for authenticated proxy
`TRUST_PROXY`	off	`1`/`true`/`yes` — honor proxy forwarded headers
`SECURE_COOKIES`	unset	`true` for HTTPS-only UI (recommended behind TLS)
`SESSION_KEY`	file under `CONFIG_PATH`	Stable cookie signing secret
`SESSION_MAX_AGE`	~1 year (seconds)	Session lifetime
`DISABLE_FRONTEND_AUTH`	`false`	`true` disables UI login (dangerous)
`LOG_LEVEL`	`info` (prod)	Frontend log verbosity
`VITE_ALLOWED_HOSTS`	unset	Dev/build host allowlist
`NZBDAV_VERSION` / `NZBDAV_COMMIT_SHA`	image build	Version display

Backend (.NET)¶

Variable	Default	Effect
`ASPNETCORE_URLS`	from hosting	Backend listen URLs
`CONFIG_PATH`	`/config`	Same as above
`LOG_LEVEL`	Information	Serilog minimum level
`LOG_BUFFER_SIZE`	`2000`	In-memory log buffer for UI (100–50000)
`STREAM_TRACE_EVENTS`	`0` (off)	Opt-in stream trace capacity; local scripts set `20000`
`TRUSTED_PROXY_CIDRS`	loopback	Comma-separated IPs/CIDRs trusted for forwarded headers
`DISABLE_WEBDAV_AUTH`	unset	Disables WebDAV auth (dangerous)
`USENET_DISABLE_CRC_VALIDATION` since 0.8.0	unset	`1` skips yEnc CRC checks (emergency)
`THREADPOOL_MIN_THREADS`	`max(2×CPU, 50)`	Override min worker/IOCP threads
`THREADPOOL_MAX_THREADS`	`max(50×CPU, 1000)`	Override max threads
`MAX_REQUEST_BODY_SIZE`	100 MiB	Max request body bytes
`NZBDAV_VERSION`	`0.0.0`	Reported app version
`DOTNET_DbgEnableMiniDump`	off	Opt-in crash dumps — Logs

Settings fallbacks (when UI empty)¶

Variable	Related setting	Default if both empty
`FRONTEND_BACKEND_API_KEY`	API Key	required
`CATEGORIES`	Categories	`audio,software,tv,movies`
`NZB_GRAB_USER_AGENT`	User Agent / retrieve UA	`nzbdav/{version}`
`NZB_SEARCH_USER_AGENT`	Search User-Agent	`nzbdav/{version}`
`TRUSTED_INTERNAL_HOSTS` since 0.8.0	Trusted local hosts	none
`MOUNT_DIR`	Rclone Mount Directory	`/mnt/nzbdav`
`WEBDAV_USER`	WebDAV User	`admin`
`WEBDAV_PASSWORD`	WebDAV Password	none (hashed when set)
`RESOLUTION_CACHE_TTL_HOURS` since 0.8.0	Search link lifetime	`168`
`DATABASE_HISTORY_RETENTION_DAYS`	History retention	`90`
`DATABASE_HEALTHCHECK_RETENTION_DAYS`	Health-check retention	`30`
`DATABASE_MAINTENANCE_INTERVAL_HOURS`	Retention sweep cadence	`6`

Example Compose snippet¶

environment:
  PUID: "1000"
  PGID: "1000"
  TZ: America/New_York
  TRUST_PROXY: "1"
  SECURE_COOKIES: "true"
  TRUSTED_INTERNAL_HOSTS: "prowlarr"

Security

Never enable DISABLE_FRONTEND_AUTH or DISABLE_WEBDAV_AUTH on a network-exposed instance. Prefer TLS + strong WebDAV passwords + SECURE_COOKIES=true.