Skip to content

docs: fix build-from-source instructions and document prerequisites#462

Merged
matteius merged 2 commits into
opensensor:mainfrom
CapnRon:docs-fix-build-from-source
Jul 26, 2026
Merged

docs: fix build-from-source instructions and document prerequisites#462
matteius merged 2 commits into
opensensor:mainfrom
CapnRon:docs-fix-build-from-source

Conversation

@CapnRon

@CapnRon CapnRon commented Jul 26, 2026

Copy link
Copy Markdown
Contributor

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) 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
    

    scripts/build_web_vite.sh already 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":

    • FFmpeg ≥ 7.1 (libavcodec ≥ 61) — Debian 12/Ubuntu 22.04 ship older FFmpeg, and the CMake pkg_check_modules failure doesn't say what version or where to get it.
    • Node.js ≥ 20 for the web build — Debian 12's packaged nodejs is 18.x. Several deps (vite, tinykeys) require 20+/22+, and chromedriver's postinstall script crashes under Node 18 with an ERR_REQUIRE_ESM error 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 with sqlite3 not found with no indication it's a missing apt package.

No functional/code changes — README only.

Test plan

  • Followed the updated instructions end-to-end on a fresh Debian 12 (bookworm) install, including the FFmpeg/Node/sqlite3 prerequisites, and confirmed scripts/build_web_vite.shscripts/build.sh --releasescripts/install.sh succeeds where the old instructions failed at the Vite build step.

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.
@github-actions

Copy link
Copy Markdown
Contributor

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?
lightNVR uses a dual-licensing model. While the project is freely available under GPLv3, OpenSensor Engineering also offers commercial licenses. The CLA ensures we can continue offering both options.

To sign the CLA, please reply to this comment with exactly:

I have read the CLA Document and I hereby sign the CLA

You only need to sign once, and it applies to all future contributions.


ℹ️ More about the CLA

The CLA grants OpenSensor Engineering the right to:

  • Include your contributions under GPLv3 (open source)
  • Offer commercial licenses that include your contributions

You retain copyright of your contributions and can use them in other projects.

- - - I have read the CLA Document and I hereby sign the CLA - - - You can retrigger this bot by commenting **recheck** in this Pull Request. Posted by the **CLA Assistant Lite bot**.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 (generates web/js/version.js via scripts/extract_version.js).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread README.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
@matteius
matteius merged commit ac9232f into opensensor:main Jul 26, 2026
1 check failed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants