OpenNVR

Local Development Setup

Local Development Setup

Complete guide for setting up OpenNVR for local development without Docker. This is necessary if you intend to write code for the React frontend, the FastAPI backend, or directly interface with MediaMTX as a service.

⚠️ CRITICAL: Local Development vs Docker Configuration

  • Local Development: Uses mediamtx.local.yml (binds strictly to 127.0.0.1 holding hardcoded placeholders) and server/.env. You must manually hardcode webhook secrets in the MediaMTX config.
  • Docker Deployment: Uses mediamtx.docker.yml (binds to 0.0.0.0) and automatically environment-injects secrets from the base .env.

Prerequisites

Ensure you have the following installed:

1. Clone Repository & Setup DB

First, download the source code:

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

Next, map a PostgreSQL database. Open your Postgres shell (psql -U postgres or sudo -u postgres psql) and run:

CREATE DATABASE opennvr;
CREATE USER opennvr_admin WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE opennvr TO opennvr_admin;
\q

2. Backend Setup

Open a terminal and navigate to your server directory to prepare the Python environment and FastAPI server.

Initialize your virtual environment & install dependencies:

cd server
uv venv .venv
# On Windows: .\.venv\Scripts\Activate.ps1
# On Linux/Mac: source .venv/bin/activate


uv pip install -r requirements.txt

Create and Configure Secrets (.env): Copy env.example to .env:

cp env.example .env

You can auto-generate the necessary backend secrets by running one of our included setup scripts from a separate terminal in the project root:

# Windows
..\scripts\generate-secrets.ps1

# Linux/Mac
bash ../scripts/generate-secrets.sh

Update your .env with the new generated secrets, specify your DATABASE_URL matching the Postgres DB you made in Step 1, and map RECORDINGS_HOST_BASE to an actual local folder on your hard drive (e.g., D:/opennvr/Recordings).

Run Database Migrations:

alembic upgrade head
# Optionally create your primary admin
python -c "from core.database import init_db; init_db()"

3. Frontend Setup

Open a new terminal, navigate to the app folder, and simply install React dependencies.

cd app
npm install

Note: No .env is required for the React Frontend in local development! OpenNVR relies purely on Vite’s local HTTP Dev Server Proxy mapping requests strictly to your FastAPI backend at http://localhost:8000.

4. MediaMTX Engine Setup

Download MediaMTX v1.15.4 for your exact Operating System here.

  1. Extract the downloaded archive directly into the mediamtx/ folder in the project root.
  2. Generate a random Hex 32 Secret using an online generator or openssl rand -hex 32.
  3. Open mediamtx.local.yml.
  4. Fine the YOUR_SECRET_HERE strings on the webhook paths, and paste your hex string.
  5. In your server/.env file, map MEDIAMTX_SECRET= to that exact same hex string so the backend can accept API connections from the streaming server.

5. Running the Stack

You must now run all components locally concurrently (meaning you will need 3 separate terminals/tabs).

Terminal 1 (Backend):

cd server
source .venv/bin/activate
py start.py 
OR
python start.py

Terminal 2 (Frontend React UI):

cd app
npm run dev

Terminal 3 (MediaMTX):

cd mediamtx
# Windows
.\mediamtx.exe mediamtx.local.yml
# Linux/Mac
./mediamtx mediamtx.local.yml

Access the fully running UI at http://localhost:5173.