Skip to content

Latest commit

 

History

History
752 lines (554 loc) · 22.8 KB

INSTALLATION.md

File metadata and controls

752 lines (554 loc) · 22.8 KB

LightNVR Installation Guide

This document provides detailed instructions for installing LightNVR on various platforms.

Table of Contents

  1. Prerequisites
  2. Installation Methods
  3. Platform-Specific Instructions
  4. Post-Installation Setup
  5. Upgrading
  6. Uninstallation

Prerequisites

Before installing LightNVR, ensure your system meets the following requirements:

  • Processor: Any Linux-compatible processor (ARM, x86, MIPS, etc.)
  • Memory: 256 MB minimum; 1 GB or more if you enable object detection — see below
  • Storage: Any storage device accessible by the OS, sized for your retention policy
  • Network: Ethernet or WiFi connection
  • OS: Linux with kernel 4.4 or newer

Memory in practice

LightNVR is built for memory-constrained hardware, so the floor is low, but "minimum" and "enough for your setup" are different numbers.

Deployment Memory
Container, started, no streams configured ~75 MB measured (LightNVR ~33 MB, go2rtc ~16 MB)
A few streams, recording only, no detection 256 MB is workable
Object detection enabled 1 GB or more — models are held in memory
Many streams, or detection across several streams 2 GB and up

The idle figure is measured from the published amd64 image on first start with no cameras. Everything above it scales with what you actually run: each stream costs buffers ([memory] buffer_size, 1024 KB per stream by default) plus whatever the decoder needs for that resolution, and object detection adds the model's working set on top.

If you are sizing a box rather than checking a floor: recording alone is cheap and mostly I/O-bound, while detection is what will decide your RAM. A swap file is supported and helps small devices survive spikes, but do not plan to run detection out of swap.

Installation Methods

Most installations should use the container image, a pre-built .deb package, or the Home Assistant add-on. Build from source for development, for embedded targets, or for an OS release without a package.

Building from Source

1. Clone the Repository

git clone https://github.com/opensensor/lightnvr.git
cd lightnvr

# Initialize submodules (required for go2rtc)
git submodule update --init --recursive

LightNVR 0.48.x requires the pinned OpenSensor go2rtc fork for live view. A stock upstream go2rtc binary does not acknowledge LightNVR's media policy. Build the submodule with ./scripts/install_go2rtc.sh (requires Go), or set [go2rtc] binary_path to your own build of the pinned submodule. The installer never falls back to an upstream binary.

For an ARMv7 cross-build, run ./scripts/install_go2rtc.sh --arch armv7l --install-dir "$PWD/staging/bin" --config-dir "$PWD/staging/go2rtc" on a Go build host, then copy the staged binary to the device.

2. Install Dependencies

See the Platform-Specific Instructions section for dependency installation commands for your distribution.

3. Build the Software

# Build in debug mode (default)
./scripts/build.sh

# Or build in release mode (recommended for production)
./scripts/build.sh --release

4. Install the Software

# Install (requires root privileges)
sudo ./scripts/install.sh

The installation script will:

  1. Install the binary to /usr/local/bin/lightnvr
  2. Install configuration files to /etc/lightnvr/
  3. Create data directories in /var/lib/lightnvr/
  4. Create a systemd service file

You can customize the installation paths using options:

sudo ./scripts/install.sh --prefix=/opt --config-dir=/etc/custom/lightnvr

See ./scripts/install.sh --help for all available options.

Direct CMake installs also default to /etc/lightnvr, matching the runtime config search path and service configuration. This default is independent of CMAKE_INSTALL_PREFIX and cmake --install --prefix. Packagers can stage the layout without writing to the host's /etc:

DESTDIR="$PWD/package-root" cmake --install build

To opt into a relocatable layout, set CMAKE_INSTALL_SYSCONFDIR to a relative directory. For example:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/lightnvr -DCMAKE_INSTALL_SYSCONFDIR=etc
cmake --build build
sudo cmake --install build

This installs configuration to /opt/lightnvr/etc/lightnvr; start LightNVR with -c /opt/lightnvr/etc/lightnvr/lightnvr.ini. Relative sysconf directories follow cmake --install --prefix; absolute overrides such as /etc/custom do not. CMake installs binaries, configuration files and migrations; it does not perform the service/data-directory setup provided by scripts/install.sh.

Docker Installation

Docker provides an easy way to run LightNVR without installing dependencies directly on your system.

Option 1: Using Docker Compose (Recommended)

Docker Compose simplifies the deployment and ensures proper volume configuration.

# Clone the repository
git clone https://github.com/opensensor/lightNVR.git
cd lightNVR

# Prepare the recordings bind mount for the image's non-root UID:GID
sudo install -d -o 10001 -g 10001 -m 0750 ./data/recordings

# Start the container from the published image
docker compose up -d

The default docker-compose.yml persists storage in three named volumes and one host directory:

  • lightnvr-config — configuration at /etc/lightnvr
  • lightnvr-database — database at /var/lib/lightnvr/data/database
  • lightnvr-models — models at /var/lib/lightnvr/data/models
  • ./data/recordings — recordings at /var/lib/lightnvr/data/recordings

Compose prefixes named volumes with its project name. If reusing a recordings directory, ensure UID:GID 10001:10001 can write it.

To customize the configuration:

# Copy the initialized configuration to a private local file
umask 077
docker compose cp lightnvr:/etc/lightnvr/lightnvr.ini ./lightnvr.ini
nano ./lightnvr.ini

# Write it back as the container user to preserve volume ownership
docker compose exec -T lightnvr sh -c 'cat > /etc/lightnvr/lightnvr.ini' < ./lightnvr.ini

# Restart the container to apply changes
docker compose restart

Option 2: Using Docker Run

1. Pull the Docker Image
docker pull ghcr.io/opensensor/lightnvr:latest
2. Create Named Volumes for Persistent Storage
docker volume create lightnvr-config
docker volume create lightnvr-database
docker volume create lightnvr-recordings
docker volume create lightnvr-models

These volumes preserve configuration, database, recordings, and models when the container is replaced. New empty volumes inherit the image's directory ownership for its non-root user.

3. Run the Container
docker run -d \
  --name lightnvr \
  --restart unless-stopped \
  -p 8080:8080 \
  --security-opt no-new-privileges --cap-drop ALL \
  -v lightnvr-config:/etc/lightnvr \
  -v lightnvr-database:/var/lib/lightnvr/data/database \
  -v lightnvr-recordings:/var/lib/lightnvr/data/recordings \
  -v lightnvr-models:/var/lib/lightnvr/data/models \
  ghcr.io/opensensor/lightnvr:latest
4. Customize the Initialized Configuration
# Copy to a private local file and edit it
umask 077
docker cp lightnvr:/etc/lightnvr/lightnvr.ini ./lightnvr.ini
nano ./lightnvr.ini

# Write it back as the container user to preserve volume ownership
docker exec -i lightnvr sh -c 'cat > /etc/lightnvr/lightnvr.ini' < ./lightnvr.ini

Note: Ensure the paths in lightnvr.ini point to /var/lib/lightnvr/data subdirectories:

  • Database: /var/lib/lightnvr/data/database/lightnvr.db
  • Recordings: /var/lib/lightnvr/data/recordings
  • MP4 recordings: /var/lib/lightnvr/data/recordings/mp4
  • Models: /var/lib/lightnvr/data/models
5. Restart the Container
docker restart lightnvr

Pre-built Packages

Pre-built packages are available from GitHub Releases.

Downloading from GitHub Releases

Visit the LightNVR Releases page and download the package matching both your architecture and your Debian suite. Assets are named lightnvr_<version>_<suite>_<arch>.deb, for example:

lightnvr_0.47.2_trixie_arm64.deb    # Debian 13 / Raspberry Pi OS (trixie), 64-bit
lightnvr_0.47.2_sid_amd64.deb       # Debian unstable, x86-64
lightnvr_0.47.2_trixie_armhf.deb    # 32-bit ARM

The suite matters: the packages link against that release's system libraries, so a sid package on a trixie system will fail to satisfy its dependencies.

From 0.47.3, each release also carries lightnvr-rs_<version>_sid_amd64.deb, the build generated from the same C sources as Rust (see rust/README.md). Install one package or the other, not both.

Debian/Ubuntu

# Substitute the version, suite and architecture you need
wget https://github.com/opensensor/lightNVR/releases/download/0.47.2/lightnvr_0.47.2_trixie_arm64.deb

# Install the package
sudo dpkg -i lightnvr_0.47.2_trixie_arm64.deb

# Install any missing dependencies
sudo apt-get install -f

Other Distributions

Only .deb packages are published. On non-Debian systems, use the container or build from source.

Platform-Specific Instructions

Debian/Ubuntu

Install Dependencies

sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    pkg-config \
    git \
    libsqlite3-dev \
    libavcodec-dev \
    libavformat-dev \
    libavutil-dev \
    libswscale-dev \
    libavfilter-dev \
    libuv1-dev \
    libcurl4-openssl-dev \
    libmbedtls-dev \
    curl \
    wget

Note: libuv1-dev is required for the HTTP server. libmbedtls-dev is required for ONVIF support and authentication system (cryptographic functions). llhttp is downloaded and built automatically by CMake if not found.

Fedora/RHEL/CentOS

Install Dependencies

sudo dnf install -y \
    gcc \
    gcc-c++ \
    make \
    cmake \
    pkgconfig \
    git \
    sqlite-devel \
    ffmpeg-devel \
    libuv-devel \
    libcurl-devel \
    mbedtls-devel \
    curl \
    wget

Note: libuv-devel is required for the HTTP server. mbedtls-devel is required for ONVIF support and authentication system (cryptographic functions).

Arch Linux

Install Dependencies

sudo pacman -S \
    base-devel \
    cmake \
    git \
    sqlite \
    ffmpeg \
    libuv \
    curl \
    wget \
    mbedtls

Note: libuv is required for the HTTP server. mbedtls is required for ONVIF support and authentication system (cryptographic functions).

Ingenic A1

The Ingenic A1 SoC requires cross-compilation. A detailed guide is provided below.

1. Set Up Cross-Compilation Toolchain

# Download and extract the toolchain
wget https://github.com/Ingenic-community/mips-linux-toolchain/releases/download/latest/mips-linux-uclibc-toolchain.tar.gz
sudo mkdir -p /opt/mips-linux-toolchain
sudo tar -xzf mips-linux-uclibc-toolchain.tar.gz -C /opt/mips-linux-toolchain

2. Install Dependencies for Cross-Compilation

# Install build tools
sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config

# Clone and build cross-compiled dependencies
git clone https://github.com/lightnvr/ingenic-dependencies.git
cd ingenic-dependencies
./build-all.sh

3. Build LightNVR for Ingenic A1

# Clone the repository
git clone https://github.com/opensensor/lightnvr.git
cd lightnvr

# Initialize submodules (required for go2rtc)
git submodule update --init --recursive

# Cross-compile by pointing the build at a CMake toolchain file
CMAKE_TOOLCHAIN_FILE=/path/to/your/mips-ingenic.cmake ./scripts/build.sh --release

scripts/build.sh passes CMAKE_TOOLCHAIN_FILE straight through to CMake, which is how all cross-compilation is driven. The repository ships cmake/toolchains/armv7-linux-gnueabihf.cmake as a working example; there is no MIPS toolchain file in-repo, so for Ingenic you supply one pointing at the toolchain you extracted above.

The binary lands at build/Release/bin/lightnvr.

4. Deploy to Ingenic A1 Device

# Copy the binary and configuration files to the device
scp build/Release/bin/lightnvr root@ingenic-device:/usr/local/bin/
scp config/lightnvr.ini root@ingenic-device:/etc/lightnvr/lightnvr.ini

# Create necessary directories on the device
ssh root@ingenic-device "mkdir -p /var/lib/lightnvr/data/recordings /var/lib/lightnvr/www /var/log/lightnvr"

# Copy the *built* web interface (web/ holds sources; web/dist/ is what gets served)
cd web && npm ci && npm run build && cd ..
scp -r web/dist/* root@ingenic-device:/var/lib/lightnvr/www/

Raspberry Pi

Raspberry Pi is a Debian system, so everything in the Debian/Ubuntu section applies. In order of least to most effort:

  1. Container — ghcr.io/opensensor/lightnvr publishes arm64 and arm/v7. See DOCKER.md. This is the path most Pi users want.
  2. .deb package — prebuilt for arm64 and armhf on the Releases page, for both Debian trixie (stable) and sid. Match the package to your OS release, not just the architecture.
  3. From source — below. Worth it if you are developing, or on an OS release we do not package for.

Before you start: do not record to the SD card

This is the mistake that kills Pi NVR builds. Continuous video writing will wear out a microSD card, and when it fails it usually takes the SQLite database with it. Put recordings — and ideally the whole data directory — on a USB SSD or HDD:

[storage]
path = /mnt/ssd/lightnvr/recordings

[database]
path = /mnt/ssd/lightnvr/database/lightnvr.db

Make sure the drive is mounted at boot (an /etc/fstab entry, not a desktop automount) before pointing LightNVR at it, or the service will start against an empty mount point.

Which Pi?

A Pi 4 or 5 with 2 GB or more handles several streams comfortably. A Pi Zero or a first-generation model will struggle with anything beyond one low-resolution stream. Object detection wants 1 GB of headroom on top of whatever your streams use — see Memory in practice.

Prefer a 64-bit OS. arm/v7 builds exist, but 32-bit ARM is the least-tested target and Home Assistant has already dropped it.

Building from source

Install dependencies
sudo apt-get update
sudo apt-get install -y \
    build-essential \
    cmake \
    pkg-config \
    git \
    libsqlite3-dev \
    libavcodec-dev \
    libavformat-dev \
    libavutil-dev \
    libswscale-dev \
    libavfilter-dev \
    libuv1-dev \
    libcurl4-openssl-dev \
    libmbedtls-dev \
    curl \
    wget

Note: libuv1-dev is required for the HTTP server. libmbedtls-dev is required for ONVIF support and authentication system (cryptographic functions).

Build and install
# Clone the repository
git clone https://github.com/opensensor/lightnvr.git
cd lightnvr

# Initialize submodules (required for go2rtc)
git submodule update --init --recursive

# Build (ARM architecture is detected automatically)
./scripts/build.sh --release

# Install
sudo ./scripts/install.sh

NAS (Synology, QNAP, unRAID, TrueNAS)

A NAS is a natural home for an NVR — it already has the disks. All of these run Docker under their own branding (Synology Container Manager, QNAP Container Station, unRAID Docker tab, TrueNAS SCALE Apps), so DOCKER.md is the reference and their own documentation covers the click-path for adding a container.

Four things are LightNVR-specific and are what people actually get wrong:

Do not put the database on a network share. Recordings on a share are fine; the SQLite database is not. NFS and SMB do not implement the file locking SQLite expects, and the result is corruption rather than an error message. Keep [database] path on local storage — the same volume the container runs from — and point only [storage] path at the big array. This applies to the NAS's own shares mounted back into the container, not just remote ones.

Bridge networking breaks ONVIF discovery. WS-Discovery is multicast and will not cross the default bridge. Either set LIGHTNVR_ONVIF_NETWORK to your camera subnet in CIDR form (the unicast sweep works through NAT), or give the container host/macvlan networking, which most NAS UIs expose. Host networking also makes WebRTC live view work without extra port mapping.

Check the UID the container runs as. These platforms often run containers as a non-root user of their choosing. The data directory must be writable by whatever that is, or LightNVR will start and then fail to record.

Mind the spin-down. If the array parks its disks, continuous recording will keep waking them, and event-triggered recording will lose the first seconds to spin-up latency. Either disable spin-down for the recording volume or accept the trade.

Ports and volumes are identical to any other Docker deployment: map /etc/lightnvr and /var/lib/lightnvr/data, never /var/lib/lightnvr itself.

Home Assistant

On Home Assistant OS or Supervised, install LightNVR from the Add-on Store by adding the repository https://github.com/opensensor/lightnvr-hassio-addons.

See LightNVR on Home Assistant for the walkthrough and for the ways the add-on differs from a plain Docker deployment — it serves the web UI on port 7800, uses host networking, and keeps recordings out of your Home Assistant backups.

Home Assistant Container and Core installs have no add-on store; use DOCKER.md there.

Windows

LightNVR is Linux software; there is no native Windows build and none is planned. On Windows you run the published Linux container.

See Running LightNVR on Windows with Podman + WSL2 for the full walkthrough, including the Windows-specific parts that are easy to get wrong: reaching the web UI from other devices on your LAN, why the database must not live on a C:\ path, and what it takes to keep a recorder running through sleep and reboots.

Docker Desktop works too, and DOCKER.md applies unchanged if you prefer it.

Post-Installation Setup

After installing LightNVR, follow these steps to complete the setup:

1. Configure LightNVR

Edit the configuration file:

sudo nano /etc/lightnvr/lightnvr.ini

At minimum, you should:

  • Set a secure password for the web interface
  • Configure storage paths
  • Set up your camera streams

See CONFIGURATION.md for detailed configuration options.

2. Start the Service

# Start the service
sudo systemctl start lightnvr

# Enable the service to start at boot
sudo systemctl enable lightnvr

3. Check the Status

sudo systemctl status lightnvr

4. Access the Web Interface

Open a web browser and navigate to:

http://your-device-ip:8080

Log in with the username and password configured in the configuration file.

Upgrading

Upgrading from Source

# Navigate to the repository
cd lightnvr

# Pull the latest changes
git pull

# Update submodules to the revisions required by the new commit
git submodule update --init --recursive

# Rebuild
./scripts/build.sh --release

# Stop the service
sudo systemctl stop lightnvr

# Install the new version
sudo ./scripts/install.sh

# Start the service
sudo systemctl start lightnvr

Upgrading Docker Installation

Using Docker Compose

The default Compose file uses the published image:

# Navigate to the repository
cd lightNVR

# Pull the latest changes
git pull

# Pull latest image and restart
docker compose pull
docker compose up -d

If you enabled the commented build: configuration instead of image:, update the source and submodules, then rebuild before recreating the service:

git pull
git submodule update --init --recursive
docker compose build --pull
docker compose up -d

Using Docker Run

# Pull the latest image
docker pull ghcr.io/opensensor/lightnvr:latest

# Stop and remove the container
docker stop lightnvr
docker rm lightnvr

# Run a new container with the latest image
docker run -d \
  --name lightnvr \
  --restart unless-stopped \
  -p 8080:8080 \
  --security-opt no-new-privileges --cap-drop ALL \
  -v lightnvr-config:/etc/lightnvr \
  -v lightnvr-database:/var/lib/lightnvr/data/database \
  -v lightnvr-recordings:/var/lib/lightnvr/data/recordings \
  -v lightnvr-models:/var/lib/lightnvr/data/models \
  ghcr.io/opensensor/lightnvr:latest

Note: Your data is preserved in the volumes, so upgrading will not affect your database or recordings.

Uninstallation

Uninstalling Source Installation

# Stop the service
sudo systemctl stop lightnvr
sudo systemctl disable lightnvr

# Remove the service file
sudo rm /etc/systemd/system/lightnvr.service
sudo systemctl daemon-reload

# Remove the binaries and migrations (default install paths)
sudo rm -f /usr/local/bin/lightnvr /usr/local/bin/lightnvr-ffmpeg-guard
sudo rm -rf /usr/local/share/lightnvr/migrations

# Remove configuration and data (optional, default paths)
sudo rm -rf /etc/lightnvr
sudo rm -rf /var/lib/lightnvr
sudo rm -rf /var/log/lightnvr

Note: If you installed with a custom --prefix or custom config/data/log directories, replace the paths above with the exact paths you chose during installation. The optional data removal also removes the installed web assets under the data directory. Separately installed go2rtc binaries and shared SOD libraries may have other consumers; remove them only if no other installation uses them.

Uninstalling Docker Installation

Using Docker Compose

# Navigate to the repository
cd lightNVR

# Stop and remove the container
docker compose down

# Remove the image
docker rmi ghcr.io/opensensor/lightnvr:latest

# Delete configuration, database, and models (optional; irreversible)
docker compose down --volumes

# Delete recordings in the bind mount separately (optional; irreversible)
sudo rm -rf ./data/recordings

Using Docker Run

# Stop and remove the container
docker stop lightnvr
docker rm lightnvr

# Remove the image
docker rmi ghcr.io/opensensor/lightnvr:latest

# Remove named volumes (optional - this will delete all data)
docker volume rm lightnvr-config
docker volume rm lightnvr-database
docker volume rm lightnvr-recordings
docker volume rm lightnvr-models