OpenNVR

Docker Setup (Recommended)

🐳 Docker Deployment & Network Configuration

OpenNVR runs as Docker services (opennvr-core, mediamtx, db, and optional ai-adapters). Correct routing depends on your OS.

1. Network Strategy (CRITICAL)

Choose your setup based on your OS. You cannot mix and match.

Option A: Bridge Mode (Windows & macOS)

Docker on PC/Mac runs inside a VM and cannot bind to physical networks for UDP multicast. You must use Bridge routing.

  • ONVIF Auto-discovery: Disabled (Add cameras manually via IP).
  • Container Addressing: Containers communicate using their service names (Docker internal DNS).
    • ❌ NEVER use 127.0.0.1 for inter-container APIs in Bridge mode.
    • ✅ Use http://opennvr_core:8000 (Core API), http://mediamtx:8889 (Video Server), http://db:5432 (Database).

Option B: Host Mode (Linux Only)

Docker natively attaches to the Linux host network layer, allowing full UDP broadcast caching.

  • ONVIF Auto-discovery: Fully supported out of the box.
  • Container Addressing: The Docker internal DNS is bypassed. All processes share the host networking layer.
    • ✅ Use 127.0.0.1 exclusively for all services (e.g., http://127.0.0.1:8000).

2. Installation & Secret Generation

First, download the source code:

git clone https://github.com/open-nvr/open-nvr.git
cd open-nvr/open-nvr

Next, generate your secure configuration files. Do not manually write symmetric secrets! Copy the environment template:

cp .env.docker .env

And then run the automatic secret generator for your OS:

Windows:

.\scripts\generate-secrets.ps1

Linux / macOS:

./scripts/generate-secrets.sh

(Note: These scripts automatically generate and inject secure Fernet keys and Admin hashes directly into your .env file!)

Finally, open .env and set RECORDINGS_PATH to an existing directory on your host (e.g., D:/Recordings or /mnt/recordings).

3. Configuring docker-compose.yml

Before building, uncomment the required network strategies in your docker-compose.yml based on the choice you made in Step 1.

Windows/Mac Users (Bridge):

  1. Search for lines starting with # [WINDOWS/MAC] BRIDGE MODE:.
  2. Uncomment the ports:, networks:, and environment: blocks directly beneath those markers.
  3. AI Adapter Configuration: If you enable ai-adapters, add - ADAPTER_URL=http://opennvr_ai:9100 to the opennvr-core environment section.

Linux Users (Host):

  1. Search for lines starting with # [LINUX] HOST MODE:.
  2. Uncomment network_mode: host and the Linux-specific environment variables.
  3. Comment out all Bridge ports: and networks: blocks.

4. Configuring Webhooks in mediamtx.docker.yml

Skip this step if you are on Linux (Host Mode).

If you are on Windows/Mac (Bridge Mode), MediaMTX cannot resolve 127.0.0.1 to refer to the core backend. It relies on the backend for WHEP WebRTC authorization and post-recording webhook actions. You must edit mediamtx.docker.yml:

Change 127.0.0.1 to the container name: opennvr_core. Your webhook endpoints should look exactly like this:

authJWTJWKS: http://opennvr_core:8000/.well-known/jwks.json
runOnRecordSegmentComplete: 'curl -X GET -H "X-MTX-Secret: ${MEDIAMTX_SECRET}" "http://opennvr_core:8000/api/v1/mediamtx/hooks/segment-complete..."'

5. Build and Boot Stack

Once your networking maps are cleanly established, orchestrate the official images:

docker compose build
docker compose up -d

Open a web browser and navigate to the frontend portal:

http://localhost:8000

Login Credentials: Check your .env file (or terminal output from the generation script) for the initial admin username and password.