Configuration

Configure OpenNVR — environment variables, secrets, storage paths, and deployment modes.

On this page

Configuration

OpenNVR is built on open standards. Configuration is accomplished using a combination of the web interface or specific files such as server/.env and docker-compose.yml.


Setting Up Your Cameras

You must use the OpenNVR UI to map endpoints since NVR routing configurations are dynamic:

  1. Navigate to the Cameras page in the UI.
  2. Select Add Camera.
  3. Name your Camera.
  4. Paste the rtsp://, rtmps://, or http:// stream endpoint from your IP Camera.
  5. In the next section, configure Retention Policies (E.g., “Retain Continuous Recording for 14 Days” or “Retain Events for 30 Days”).

✅ ONVIF Discovery: From Cameras → Add Camera → Discover, OpenNVR scans your local subnet for reachable ONVIF cameras and lists them. Discovery uses a unicast subnet scan, so it works the same in Docker bridge mode on Windows, macOS, and Linux — no host networking required. You can always add a camera by its RTSP URL if discovery is blocked by network/firewall rules.

Storage Configurations

Recordings are saved to ./recordings (relative to the compose file) by default. For production, point the recording volume at a physical drive or NAS by setting RECORDINGS_PATH in .env:

# Linux
RECORDINGS_PATH=/var/lib/opennvr/recordings
# Windows
RECORDINGS_PATH=D:/opennvr-recordings

Then re-run docker compose -f docker-compose.yml up -d to remount. Ensure the Docker daemon has read/write permissions for that directory. See Storage Mapping for details.

Every visit Tier-0 records is a row in the event store. Three background enrichers add words to it after the fact so search can answer “blue car on the gate camera between two and four”: a caption (one sentence, from BLIP / Moondream / ollamavlm), descriptors (colour, vehicle type, what someone carries — VQA questions), and an embedding (CLIP). They run off the ingest path, best effort, only on cameras an enabled app has pointed the skill at.

What they power is the Search page: type what you are looking for in plain words and get the matching visits, each with its evidence frame.

Search — a plain-language question answered with matching visits and their evidence frames
Variable Default What it does
EVENTS_CAPTION_ENRICHMENT true (false without a CUDA GPU — the installer asks) describe each qualifying visit in a sentence
EVENTS_DESCRIPTOR_ENRICHMENT same colour / type / attribute claims, two VQA questions per visit
EVENTS_DESCRIPTOR_PEOPLE false extend descriptors to people, not only vehicles
CAPTION_ADAPTER ollamavlm which captioner image runs. On CPU or Apple Silicon use moondream — the 0.5B in-container build, ~10× faster than ollamavlm there
EVENTS_ENRICHMENT_BACKFILL false describe history newest-first when the box is idle, then keep catching up on visits dropped under load
EVENTS_ENRICHMENT_QUEUE_DEPTH 8 visits allowed to wait for an adapter slot; the next is dropped, not queued
EVENTS_ENRICHMENT_TIMEOUT_S 90 per-call ceiling (a hung-adapter guard, not load control)
EVENTS_ENRICHMENT_BREAKER_TIMEOUTS 5 timeouts in a row that pause that adapter (60 s, doubling to 10 min)
EVENTS_ENRICHMENT_GOVERNOR_CPU_PERCENT 65 above this CPU the live path goes LIVE-ONLY (claims keep a short line, captions only when a slot is free, backfill held)
EVENTS_ENRICHMENT_SLOW_CALL_S 20 an adapter averaging more than this per call counts as behind
EVENTS_ENRICHMENT_BACKFILL_IDLE_S 120 quiet time before the backfill may run
EVENTS_ENRICHMENT_BACKFILL_WINDOW (empty) optional HH:MM-HH:MM local window for the backfill only
EVENTS_ENRICHMENT_REQUEST_CAP 50 visits one search question may queue for description on demand

Enrichment never slows recording or detection. When the box cannot keep up it yields: a per-adapter gate drops rather than queues, a breaker pauses a stalled adapter, and a governor steps the live path down as CPU or adapter latency climbs. Each change is one enrichment_throttled system event with the reason.

Search says “not yet”, not “no”. A question that needs a caption or a claim the matching visits do not carry yet answers from what exists and queues the rest for description now — even with the two flags off, because you asked. The Search page shows N of the matching visits have not been described yet — describing them now, about T with a Check again button; the agent says it in words; the API returns it as pending on GET /api/v1/search (describe=false queues nothing).

Full detail, including the per-camera skill gate and how to turn it on in order: docs/ENRICHMENT.md.

Secrets & TLS

Application secrets. ./scripts/generate-secrets.sh (or .ps1 on Windows) writes cryptographically random values into .env for the four secrets the core validates at boot — SECRET_KEY, CREDENTIAL_ENCRYPTION_KEY, INTERNAL_API_KEY, MEDIAMTX_SECRET — plus the PostgreSQL password. The launcher runs this for you; run it by hand only for the manual/unattended install. There are no shipped default credentials.

TLS certificates. The launcher (./start.sh / .\start.ps1) auto-generates a self-signed certificate into ./nginx-certs/ for the HTTPS UI at https://localhost/ — accept the browser warning once. The cert never leaves the host. If your LAN IP changes, regenerate with ./start.sh refresh-certs. For a public deployment, front OpenNVR with a real reverse proxy (Caddy, Traefik, nginx) holding a CA-issued certificate.

Logs

All logs are emitted via stdout to Docker. You can monitor OpenNVR’s core operations anytime:

docker compose logs -f opennvr-core