docs: fix build-from-source instructions and document prerequisites#462
Conversation
The documented web build (cd web && npm install && npm run build) skips scripts/extract_version.js, which generates web/js/version.js from CMakeLists.txt. Without it, the Vite build fails outright: [UNRESOLVED_IMPORT] Could not resolve '../../version.js' in js/components/preact/Header.jsx Point at scripts/build_web_vite.sh instead, which runs that step first. Also document three prerequisites that aren't mentioned anywhere and will otherwise surface as confusing failures partway through the build: - FFmpeg >= 7.1 (libavcodec >= 61) -- Debian 12/Ubuntu 22.04 ship older FFmpeg and the CMake configure step fails on the pkg-config version check with no guidance on what's required. - Node.js >= 20 for the web build -- Debian 12's packaged Node is 18.x; several deps (vite, tinykeys) require 20+/22+, and chromedriver's postinstall script crashes outright under 18 with an ERR_REQUIRE_ESM error that doesn't point at the actual cause (Node version). - libsqlite3-dev -- not pulled in by any of the previously-listed build-essential/cmake/pkg-config packages, and CMake configure fails with 'sqlite3 not found' with no indication it's a missing apt package rather than a build system problem. Verified building from a stock Debian 12 (bookworm) install.
|
Thank you for your contribution to lightNVR! 🎉 Before we can merge your pull request, we need you to sign our Contributor License Agreement (CLA). Why a CLA? To sign the CLA, please reply to this comment with exactly: You only need to sign once, and it applies to all future contributions. ℹ️ More about the CLAThe CLA grants OpenSensor Engineering the right to:
You retain copyright of your contributions and can use them in other projects. |
There was a problem hiding this comment.
Pull request overview
Updates the build-from-source documentation to reduce common build failures on fresh Debian/Ubuntu systems by documenting missing prerequisites and pointing users to the existing web build script that performs required version extraction.
Changes:
- Adds a prerequisites list for source builds (FFmpeg versioned libs, Node.js, sqlite3 dev headers).
- Replaces manual web build steps with
./scripts/build_web_vite.sh, documenting why it’s required (generatesweb/js/version.jsviascripts/extract_version.js).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Summary
Hit these building from a stock Debian 12 (bookworm) install and want to save the next person the trial-and-error:
The documented web build step (
cd web && npm install && npm run build) skipsscripts/extract_version.js, which generatesweb/js/version.jsfromCMakeLists.txt. Without it, the Vite build fails outright:scripts/build_web_vite.shalready exists and runs that step first — the README should point at it instead of the manual npm commands.Three prerequisites aren't documented anywhere and surface as confusing failures partway through the build rather than an upfront "you need X":
libavcodec ≥ 61) — Debian 12/Ubuntu 22.04 ship older FFmpeg, and the CMakepkg_check_modulesfailure doesn't say what version or where to get it.nodejsis 18.x. Several deps (vite,tinykeys) require 20+/22+, andchromedriver's postinstall script crashes under Node 18 with anERR_REQUIRE_ESMerror that gives no hint the actual cause is the Node version.libsqlite3-dev— not pulled in by any of the previously-listed packages; CMake configure fails withsqlite3 not foundwith no indication it's a missing apt package.No functional/code changes — README only.
Test plan
scripts/build_web_vite.sh→scripts/build.sh --release→scripts/install.shsucceeds where the old instructions failed at the Vite build step.