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:
- Navigate to the Cameras page in the UI.
- Select Add Camera.
- Name your Camera.
- Paste the
rtsp://,rtmps://, orhttp://stream endpoint from your IP Camera. - 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.
Visit enrichment: captions, descriptors and search
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.
| 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