Configuration¶

Orb is configured in two layers:

• Environment variables set the infrastructure the server boots against — database, key-value store, ports, storage paths, and feature toggles. These are read once at startup.
• The admin UI handles everything an operator changes at runtime: libraries, metadata-provider credentials, SMTP, integrations, and more. These are stored in the database, so non-technical admins never have to touch a config file. Anything covered here under Admin settings lives in the UI.

Docker secrets. Any variable also accepts a <NAME>_FILE companion that points at a file whose contents are used as the value — the convention Docker and Compose use for secrets mounted under /run/secrets. The bundled stack uses this for the database password and JWT secret.

Core¶

Database (PostgreSQL)¶

Provide a full DSN, or let Orb assemble one from parts:

• DATABASE_URL — full Postgres DSN, e.g. postgres://orb:secret@postgres:5432/orb?sslmode=disable. If set, it wins.
• Otherwise the DSN is built from DB_HOST (default postgres), DB_PORT (5432), DB_USER (orb), DB_NAME (orb), DB_SSLMODE (disable), and DB_PASSWORD — typically supplied as a Docker secret via DB_PASSWORD_FILE. If no password is available, the DSN is empty and the database driver surfaces a clear error.

Key-value store (Valkey / Redis)¶

Sessions, the playback queue, listen-party state, and rate limiting all use the key-value store.

• KV_MODE — standalone or sentinel (default: standalone).
• KV_ADDR — address of Valkey/Redis (default: localhost:6379; used when KV_MODE=standalone).
• KV_SENTINEL_ADDRS — comma-separated sentinel addresses (default: localhost:26379; used when KV_MODE=sentinel).
• KV_SENTINEL_MASTER — sentinel master name (default: mymaster).
• KV_OPTIONAL — if true, a key-value connection failure at startup logs a warning instead of aborting (default: false). Leave this off in production: features that depend on the store will 500 until it is reachable.

Networking & discovery¶

• SITE_ALLOWED_ORIGINS — comma-separated extra origins allowed for CORS and WebSocket connections (listen party, live ingest status). Same-origin requests always work; set this only when the web app is served from a different origin than the API.
• MDNS_ENABLED — advertise the server over mDNS for LAN discovery by the native apps (default: true).
• SERVER_NAME — display name advertised via mDNS and DLNA (default: the detected hostname).

Video transcoding¶

The container ships an ffmpeg build with hardware encoders; Orb auto-detects what the host exposes. See Installation → Hardware acceleration for the per-platform GPU passthrough setup.

• VIDEO_HWACCEL — force a transcode pipeline instead of auto-detecting: none, nvenc, qsv, vaapi, amf, or videotoolbox. On startup the API logs the chosen pipeline (video: hwaccel family=…) — check that line to confirm the GPU is in use.
• VIDEO_TRANSCODE_CAP — maximum number of concurrent video transcode sessions (default: 0, unlimited). Set this to the number of streams your encoder can sustain; the next viewer past the cap is queued server-side instead of overloading the GPU.

Chromecast¶

The Chromecast proxy is off by default and intended for LAN-only deployments — its routes are public because cast devices can't authenticate. See Remote playback & clients.

• CAST_ENABLED — enable the Chromecast proxy (default: false).
• CAST_BASE_URL — base URL the proxy advertises to cast devices (default: auto-detected LAN IP + HTTP_PORT).

The admin Disable LAN cast toggle can flip the proxy off at runtime without a restart.

DLNA / UPnP¶

DLNA is also off by default and LAN-only — its HTTP routes expose the library without auth. See Remote playback & clients.

• DLNA_ENABLED — enable the DLNA/UPnP server and SSDP advertisement (default: false).
• DLNA_BASE_URL — base URL advertised to DLNA control points (default: auto-detected LAN IP + HTTP_PORT).

Podcasts¶

• PODCAST_DEFAULT_RSS_URLS — comma-separated RSS feed URLs seeded on first boot only, e.g. https://feeds.megaphone.fm/thispastweekend,https://podcast.darknetdiaries.com/. After the first boot, manage subscriptions from the UI.

Database backup tooling¶

The admin backup/restore feature shells out to the Postgres client tools:

• PG_DUMP_BIN — path or name of pg_dump (default: pg_dump).
• PG_RESTORE_BIN — path or name of pg_restore (default: pg_restore).

Admin settings¶

The following are configured from the web UI and stored in the database — there are no environment variables for them:

• Libraries (Admin → Libraries) — media roots and per-library scan settings (workers, exclude globs, enrichment toggles, metadata-provider selection). One row per library; supports music, audiobook, movie, TV, and comic types. See Your library.
• Metadata plugins (Admin → Plugins) — API keys and credentials for the metadata providers (TMDB, Comic Vine, Metron, Marvel, …). See Metadata plugins.
• Integrations (Admin → Settings → Integrations) — TMDB/TVDB keys, OpenSubtitles credentials, and the Spotify OAuth app used for playlist import.
• Email (SMTP) (Admin → Settings) — outbound mail for email verification and invites, with a test-send button.
• Backup & restore (Admin → Settings) — download a full database dump or restore from one.
• Webhooks (Admin → Settings) — fire HTTP callbacks on library and playback events.

Next steps¶

• Your library — register media roots and lay out your files.
• Metadata plugins — configure enrichment providers.