# Environment variables

Advanced reference for **process / container** wiring and **legacy Settings fallbacks**. Most day-to-day tunables live in the Settings UI (SQLite).

:::tip[Authoritative headless Settings]
<a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v0.9.0">since 0.9.0</a>

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](https://www.infinidysk.com/v1/configuration/headless/)**. 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 {#container-entrypoint}

| Variable | What it does |
|---|---|
| `CONFIG_PATH` | SQLite, blobs, backups, session key. Must already exist as a writable directory before startup; the backend does not create a missing path. Default `/config`. |
| `PUID` / `PGID` | Container user/group for `/config` ownership. Default `1000`. |
| `TZ` | Schedules and log timestamps. Default unset. |
| `BACKEND_URL` | Frontend → backend (set by entrypoint if empty). Default `http://localhost:8080`. |
| `FRONTEND_BACKEND_API_KEY` | Shared frontend↔backend API key. The backend also uses it as the SABnzbd API key while **API Key** (`api.key`) is empty; it never writes `api.key`. Default random, generated by the entrypoint on each start when unset. |
| `METRICS_REQUIRE_API_KEY` | Require `x-api-key` for direct backend `/metrics` scrapes. Default `false`. |
| `MAX_BACKEND_HEALTH_RETRIES` | Entrypoint health wait. Default `30`. |
| `MAX_BACKEND_HEALTH_RETRY_DELAY` | Seconds between health probes. Default `1`. |

## Frontend (Node)

| Variable | What it does |
|---|---|
| `PORT` | HTTP listen port. Default `3000`. |
| `BACKEND_URL` | Backend base URL. Default required in split deploys. |
| `FRONTEND_BACKEND_API_KEY` | Injected as `x-api-key` for authenticated proxy. Default required. |
| `TRUST_PROXY` | `1`/`true`/`yes` enables and `0`/`false`/`no` disables proxy-header trust, overriding **Settings → General → Trust reverse-proxy headers**. Default Settings value. |
| `SECURE_COOKIES` | `true` for HTTPS-only UI (recommended behind TLS). Default unset. |
| `SESSION_KEY` | Stable cookie signing secret. Default file under `CONFIG_PATH`. |
| `SESSION_MAX_AGE` | Session lifetime. Default ~1 year (seconds). |
| `DISABLE_FRONTEND_AUTH` | `true` disables UI login (**dangerous**). Default `false`. |
| `LOG_LEVEL` | Frontend log verbosity. Default `info` (`debug` when `NODE_ENV=development`); the Docker image sets `warning`. |
| `VITE_ALLOWED_HOSTS` | Dev/build host allowlist. Default unset. |
| `NZBDAV_VERSION` / `NZBDAV_COMMIT_SHA` | Version display. Default image build. |
| `SERVICE_PROVIDER` | Hosted-service branding and UI navigation feature gating. Default unset. |

## `SERVICE_PROVIDER` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v0.10.0">since 0.10.0</a>

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:

```yaml
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 footer
- `url`: provider website using `http` or `https` (used in the footer link)
- `disabledFeatures`: navigation identifiers to make unavailable

Optional:

- `supportUrl`: support page using `http` or `https`, used for the "Contact"
  link in the disabled-feature dialog; falls back to `url` when 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 | What it does |
|---|---|
| `ASPNETCORE_URLS` | Backend listen URLs. Default from hosting. |
| `CONFIG_PATH` | Same as above. Default `/config`. |
| `LOG_LEVEL` | Serilog minimum level. Default `Information`; the Docker image sets `warning`. |
| `LOG_BUFFER_SIZE` | In-memory log buffer for UI (100–50000). Default `2000`. |
| `STREAM_TRACE_EVENTS` | Opt-in stream trace capacity, always-on with no expiry; the Settings → Support toggle can also set capacity (20k–200k) for timed captures. Default `0` (off). |
| `ENABLE_API_DOCS` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.2.0">since 1.2.0</a> | Enables the contributor-facing Scalar reference at `/scalar/` and its admin-only OpenAPI document at `/openapi/admin.json`; never enabled by default in Docker. Default `false`. |
| `TRUSTED_PROXY_CIDRS` | Comma-separated IPs/CIDRs trusted for forwarded headers. Default loopback. |
| `DISABLE_WEBDAV_AUTH` | Disables WebDAV auth (**dangerous**). Default unset. |
| `RESET_ADMIN_PASSWORD` | `true` deletes the admin account on next startup, forcing re-onboarding. **Remove after use.**. Default unset. |
| `USENET_DISABLE_CRC_VALIDATION` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v0.8.0">since 0.8.0</a> | `1` skips yEnc CRC checks (emergency). Default unset. |
| `THREADPOOL_MIN_THREADS` | Override min worker/IOCP threads. Default `max(2×CPU, 50)`. |
| `THREADPOOL_MAX_THREADS` | Override max threads. Default `max(50×CPU, 1000)`. |
| `NZBDAV_SEGMENT_BUFFER_POOL` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.3.0">since 1.3.0</a> | Segment-buffer retention. Unset and `bounded-capacity` use the production idle-byte cap of about 34–268 MB without a per-class ceiling; idle buffers are kept while streams are active and released once the pool has been quiet for 30 seconds. `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`. Default `bounded-capacity`. |
| `DOTNET_GCHeapHardLimit` | .NET managed-heap ceiling; hexadecimal bytes. Default runtime default. |
| `DOTNET_GCHeapHardLimitPercent` | .NET managed-heap ceiling as a hexadecimal percentage. Default runtime/container default. |
| `DOTNET_GCRegionRange` | .NET regions-GC virtual reservation; hexadecimal bytes. Default runtime default. |
| `DOTNET_GCRegionSize` | .NET SOH region size; hexadecimal bytes. Default runtime default. |
| `DOTNET_GCConserveMemory` | .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. Default `0`. |
| `DOTNET_gcServer` | Enables (`1`) or disables (`0`) server GC. Default image default (`1`). |
| `MAX_REQUEST_BODY_SIZE` | Max request body bytes. Default `314572800` (about 315 MB). |
| `QUEUE_ITEM_STUCK_MINUTES` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v1.1.0">since 1.1.0</a> | Minutes without queue progress before the stuck-item watchdog pauses and cancels the worker. Default `5`. |
| `NZBDAV_VERSION` | Reported app version. Default `0.0.0`. |
| `DOTNET_DbgEnableMiniDump` | Opt-in crash dumps — [Logs](https://www.infinidysk.com/v1/operations/logs-crash-dumps/). Default off. |

`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](https://www.infinidysk.com/v1/getting-started/docker/#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](https://www.infinidysk.com/v1/operations/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__...`](https://www.infinidysk.com/v1/configuration/headless/) overlay supplies that key.

| Variable | What it does |
|---|---|
| `FRONTEND_BACKEND_API_KEY` | Related setting: API Key (`api.key`). Read at runtime while `api.key` is empty; never written to it. |
| `CATEGORIES` | Related setting: Categories. Default if both empty `audio,software,tv,movies`. |
| `NZB_GRAB_USER_AGENT` | Related setting: User Agent / retrieve UA. Default if both empty `SABnzbd/5.1.0`. |
| `NZB_SEARCH_USER_AGENT` | Related setting: Search User-Agent. Default if both empty `nzbdav/{version}`. |
| `TRUSTED_INTERNAL_HOSTS` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v0.8.0">since 0.8.0</a> | Related setting: Trusted local hosts. Default if both empty none. |
| `MOUNT_DIR` | Related setting: Rclone Mount Directory. Default if both empty `/mnt/nzbdav`. |
| `WEBDAV_USER` | Related setting: WebDAV User. Default if both empty `admin`. |
| `WEBDAV_PASSWORD` | Related setting: WebDAV Password. Default if both empty none (hashed when set). |
| `RESOLUTION_CACHE_TTL_HOURS` <a class="since" href="https://github.com/infinidysk/infinidysk/releases/tag/v0.8.0">since 0.8.0</a> | Related setting: Search link lifetime. Default if both empty `168`. |
| `DATABASE_HISTORY_RETENTION_DAYS` | Related setting: History retention. Default if both empty `90`. |
| `DATABASE_HEALTHCHECK_RETENTION_DAYS` | Related setting: Health-check retention. Default if both empty `30`. |
| `DATABASE_MAINTENANCE_INTERVAL_HOURS` | Related setting: Retention sweep cadence. Default if both empty `6`. |

## Example Compose snippet

Operational wiring only — for a full Settings-via-ENV stack see the
[headless Compose example](https://www.infinidysk.com/v1/configuration/headless/#fully-hydrated-compose-example).

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

:::danger[Security]
Never enable `DISABLE_FRONTEND_AUTH` or `DISABLE_WEBDAV_AUTH` on a network-exposed instance. Prefer TLS + strong WebDAV passwords + `SECURE_COOKIES=true`.
:::