Environment variables¶
Advanced reference for process / container wiring and legacy Settings fallbacks. Most day-to-day tunables live in the Settings UI (SQLite).
Authoritative headless Settings since 0.9.0
To drive every Settings (ConfigItems) value from the environment — with read-only UI locks and values kept out of SQLite — use the NZBDAV_CONFIG__... overlay documented in Headless environment configuration. That page includes a fully hydrated Compose example.
Precedence when both are present: NZBDAV_CONFIG__... > SQLite/UI > legacy fallbacks on this page > defaults.
Container / entrypoint¶
| Variable | Default | Effect |
|---|---|---|
CONFIG_PATH |
/config |
SQLite, blobs, backups, session key. Must already exist as a writable directory before startup; the backend does not create a missing path. |
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 |
METRICS_REQUIRE_API_KEY |
false |
Require x-api-key for direct backend /metrics scrapes |
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 |
Settings value | 1/true/yes enables and 0/false/no disables proxy-header trust, overriding Settings → General → Trust reverse-proxy 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 |
SERVICE_PROVIDER |
unset | Hosted-service branding and UI navigation feature gating |
SERVICE_PROVIDER since 0.10.0¶
Hosted InfiniDysk services can identify the service provider and mark selected navigation destinations as unavailable. Disabled destinations remain visible in the sidebar; selecting one explains that the feature is disabled by the provider and links to the provider's support page (or website). The provider attribution also appears in the page footer.
Set SERVICE_PROVIDER to a JSON object on the frontend process:
environment:
SERVICE_PROVIDER: >-
{"name":"ElfHosted","url":"https://elfhosted.com","supportUrl":"https://docs.elfhosted.com","disabledFeatures":["watchtower","search","settings.indexers","settings.profiles","settings.watchtower","settings.warden","settings.rclone"]}
The object requires:
name: service provider name shown in the dialog and footerurl: provider website usinghttporhttps(used in the footer link)disabledFeatures: navigation identifiers to make unavailable
Optional:
supportUrl: support page usinghttporhttps, used for the "Contact" link in the disabled-feature dialog; falls back tourlwhen omitted
Top-level navigation identifiers are overview, queue, watchdog,
watchtower, explore, health, logs, and search. overview cannot be
disabled — it is the app's landing page and the fallback destination when
closing the "feature not available" dialog, so it always stays reachable.
Settings navigation identifiers are settings.usenet, settings.indexers,
settings.profiles, settings.queue, settings.sabnzbd,
settings.streaming, settings.webdav, settings.watchdog,
settings.preflight, settings.watchtower, settings.warden,
settings.arrs, settings.rclone, settings.repairs,
settings.maintenance, settings.backup, settings.support, and
settings.migration.
This controls frontend presentation only. Providers must separately configure or restrict backend capabilities when enforcement is required.
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, always-on with no expiry; the Settings → Support toggle can also set capacity (20k–200k) for timed captures |
ENABLE_API_DOCS since 1.2.0 |
false |
Enables the contributor-facing Scalar reference at /scalar/ and its admin-only OpenAPI document at /openapi/admin.json; never enabled by default in Docker |
TRUSTED_PROXY_CIDRS |
loopback | Comma-separated IPs/CIDRs trusted for forwarded headers |
DISABLE_WEBDAV_AUTH |
unset | Disables WebDAV auth (dangerous) |
RESET_ADMIN_PASSWORD |
unset | true deletes the admin account on next startup, forcing re-onboarding. Remove after use. |
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 |
NZBDAV_SEGMENT_BUFFER_POOL since 1.3.0 |
bounded-capacity |
Segment-buffer retention. Unset and bounded-capacity use the production 32–256 MiB idle-byte cap without expiry or a per-class ceiling. bounded-legacy restores the previous two-minute expiry and 64-buffer class ceiling as a restart-only rollback. shared uses ArrayPool<byte>.Shared as an emergency escape hatch. Unknown values log a Warning and use bounded-capacity. |
DOTNET_GCHeapHardLimit |
runtime default | .NET managed-heap ceiling; hexadecimal bytes |
DOTNET_GCHeapHardLimitPercent |
runtime/container default | .NET managed-heap ceiling as a hexadecimal percentage |
DOTNET_GCRegionRange |
runtime default | .NET regions-GC virtual reservation; hexadecimal bytes |
DOTNET_GCRegionSize |
runtime default | .NET SOH region size; hexadecimal bytes |
DOTNET_GCConserveMemory |
0 |
.NET heap-conservation level (0–9). Read only at process start; a change requires a restart. Higher values compact the LOH more aggressively and can increase collection frequency and pause duration — start as a measured canary, not a fleet default. |
DOTNET_gcServer |
image default (1) |
Enables (1) or disables (0) server GC |
MAX_REQUEST_BODY_SIZE |
300 MiB | Max request body bytes |
QUEUE_ITEM_STUCK_MINUTES since 1.1.0 |
5 |
Minutes without queue progress before the stuck-item watchdog pauses and cancels the worker |
NZBDAV_VERSION |
0.0.0 |
Reported app version |
DOTNET_DbgEnableMiniDump |
off | Opt-in crash dumps — Logs |
PORT and ASPNETCORE_URLS control listeners inside the container; they do not
change Docker's published host port. For normal Compose deployments, leave the
internal ports unchanged and use a HOST_PORT:CONTAINER_PORT mapping. See
Change the published port
for bridge networking, host networking, healthcheck, and DUMB examples.
DOTNET_* variables are .NET runtime settings rather than InfiniDysk
configuration. Environment-variable numeric values are hexadecimal where the
.NET runtime requires it. See Memory-constrained hosts
before setting heap or region limits, especially on a host that enforces
ulimit -v.
Settings fallbacks (when UI empty)¶
These apply only when the matching Settings value is empty and no
NZBDAV_CONFIG__... overlay supplies that key.
| 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 | SABnzbd/5.1.0 |
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¶
Operational wiring only — for a full Settings-via-ENV stack see the headless Compose example.
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.