Epic: Documentation overhaul

[matteius]

Why now

Two recent issues were really documentation gaps wearing other clothes:

• The database version is severely outdated. #489 — a user reported an outdated SQLite version. The shipped images were fine (3.53.4 on all three architectures); what was missing was any documentation of how to tell what a container is actually running, or that sqlite_version() reports the client's engine rather than anything stored in the database. While tracing it, the README turned out to advertise matteius/lightnvr:latest and docs/INSTALLATION.md to advertise lightnvr/lightnvr:latest — neither is a published image.
• Windows? #490 — "Windows?" was closed with a correct support decision (containers, no native build), and the reporter's follow-up was simply "Do you recommend any guide or tutorial?" We had nothing to point at.

Neither user was confused about LightNVR. They were confused because we hadn't written the page.

This epic tracks a pass over the documentation with a bias toward things that are actively wrong first, structure second.

---

Phase 0 — Correctness

Documentation that states something untrue is worse than no documentation. These are all verified against the current code.

• Default credentials were documented as auto-generated; they are not. db_auth_init() in src/database/db_auth.c falls back to the literal string "admin". Random generation existed once and was intentionally removed in 453fbbd. Every install gets admin / admin, and the web server binds 0.0.0.0 by default. We were telling users to go find a generated password in the logs, which invites them to leave the default in place believing it is random. Rewritten in:
  • README.md — the "Auto-Generated Credentials (v0.21.7)" feature entry is now "Database-Backed User Management", plus a new First login section carrying the warning and the recovery procedure
  • docs/DOCKER.md — quick-start comment and the Default Credentials block
  • docs/CONFIGURATION.md — both [web] examples, the password key description, and a warning block
  • docs/TROUBLESHOOTING.md — the auth-recovery steps were wrong in a second way: users live in the database, so editing password in lightnvr.ini does nothing for an account that already exists. Replaced with the delete-the-row-and-restart procedure that actually works.
• Decision: keep the admin / admin default, document it as a warning, and make it hard to keep by gating new installs behind a forced password change — tracked in Require admin password change on first login #493.
• Secondary: the first-run banner in db_auth_init() printed Password: admin unconditionally, including when a config-file password was used — wrong in the one case where the operator did the right thing, and it contradicted the newly documented "pre-set the password before first start" path. Now reports which credential is actually valid.
• Phantom registry references. matteius/lightnvr (Docker Hub, zero tags) and lightnvr/lightnvr (does not exist) removed in favor of ghcr.io/opensensor/lightnvr, which is what docker-publish.yml actually pushes.
• Minimum memory — replaced the "unknown what the minimum is" placeholder with a measured table: ~75 MB for the started container with no streams, 256 MB for a few streams without detection, 1 GB+ with detection.
• Code-block sweep. Script flags were all real (the suspicious hits were journalctl invocations). What was wrong: the web-asset copy that does not happen, two environment variables nothing reads, a diagnostic script that never existed, a build-ingenic.sh that never existed, a .tar.gz release asset that is not published, and a .deb download URL missing the Debian suite.

Phase 1 — Platform coverage

• Windows via Podman + WSL2 — docs/WINDOWS_PODMAN.md. Covers the parts that actually bite: podman binds published ports to 127.0.0.1 only (so LAN access needs mirrored networking or netsh portproxy), the SQLite database must not live on a C:\ bind mount, ONVIF multicast discovery does not cross WSL's NAT, and keeping a 24/7 recorder alive across logon/sleep/reboot.
• Home Assistant add-on — docs/HOME_ASSISTANT.md. The add-on lives in opensensor/lightnvr-hassio-addons and documents its own options there; this guide is the discovery point and covers the deviations from a plain Docker deployment (port 7800, host networking, recordings kept out of HA backups) plus the MQTT step that actually makes Home Assistant aware of detections.
• NAS — covered as one section in INSTALLATION.md. Deliberately not three per-vendor click-path guides: their UIs change and I cannot verify them. What it does cover is the LightNVR-specific part — database off network shares, bridge networking vs ONVIF multicast, container UID, disk spin-down.
• Raspberry Pi — leads with the container and .deb, and opens with the SD-card wear problem that kills Pi NVR builds.

Phase 2 — Structure

docs/ holds 32 files with no index, mixing user-facing guides with internal design notes (PRD_*, SUMMARY_*, *_REFACTORING, *_IMPLEMENTATION, GO2RTC_CAMERA_RECONNECTION_FIX). Some have not been touched since April 2025. A newcomer cannot tell which files are for them.

• docs/README.md — grouped by task, opening with a getting-started path.
• docs/internal/ — nine historical writeups moved, plus the retention PRD into docs/prd/. Eight of the nine had zero inbound links from anywhere.
• Getting-started path — install → change the password → add a camera → verify recording → set retention → optional detection, at the top of docs/README.md.
• docs/CAMERAS.md — requirements, how to find an RTSP URL by asking the camera rather than from stale vendor lists, and a vendor table built only from real linked issues that were really fixed. No invented compatibility matrix.

Phase 3 — Keeping it true

• CI link check — scripts/check_docs_links.py, run by the Documentation Links workflow and locally the same way. Found seven dead links on its first run.
• Release checkpoint — a table in RELEASE_PROCESS.md mapping each kind of change to the documents that must change with it. Every row is there because it was wrong at some point.
• Version stamps — on the guides whose behavioral claims were checked against a running 0.37.x.

---

Not in scope

Rewriting ARCHITECTURE.md or API.md. Both are large, current, and serve their audience.

Landed so far

• docs/WINDOWS_PODMAN.md — Windows via Podman + WSL2, linked from the README index, INSTALLATION.md, and DOCKER.md
• Phantom registry references replaced with ghcr.io/opensensor/lightnvr
• The credentials rewrite across four documents, plus the startup-banner correction

Next up: docs/INSTALLATION.md's minimum-memory placeholder, and the Phase 2 index — the
structural problem is what makes everything else hard to find.

[matteius]

First batch landed on main in 410e9b5.

• docs/WINDOWS_PODMAN.md added and linked from the README index, INSTALLATION.md, and DOCKER.md — answers Windows? #490, which had no page to point at
• Phantom registry references replaced with ghcr.io/opensensor/lightnvr across README and INSTALLATION.md — the trigger from The database version is severely outdated. #489
• The credentials rewrite across README, DOCKER.md, CONFIGURATION.md, and TROUBLESHOOTING.md, following the decision to keep admin / admin and gate it instead (Require admin password change on first login #493)
• db_auth.c: the first-run banner no longer claims Password: admin when the operator supplied their own password in the config file

Phase 0 still has the INSTALLATION.md minimum-memory placeholder and the code-block sweep. Phase 2's index is the one that unblocks everything else — 32 files in docs/ with no way to tell which are for users and which are internal design notes.

[matteius]

Phase 1's Home Assistant item is done — docs/HOME_ASSISTANT.md, landed in c4dd44e.

The add-on itself was already well documented in opensensor/lightnvr-hassio-addons; the gap was that this repository never mentioned it existed, so a Home Assistant user reading our docs would find DOCKER.md and reasonably conclude that was the only path. The new guide is the discovery point, linked from the README index, INSTALLATION.md, DOCKER.md, and the Home Assistant section of MQTT_INTEGRATION.md.

It deliberately does not restate the add-on's option reference — that lives in the add-on repo's DOCS.md and tracks its own releases, so duplicating it here would just create drift. What it covers instead is what a reader of DOCKER.md would otherwise get wrong: whether the add-on suits them at all (OS/Supervised only, amd64/aarch64 only), the four places it deviates from a plain Docker deployment, that installing it does not by itself make Home Assistant aware of detections, and which of the two repositories to file an issue against.

Two things noticed while writing it, neither blocking:

• The add-on is pinned to 0.37.1 in both config.yaml and build.yaml, while this repo has since tagged 0.37.2. There is a sync-upstream-version workflow in that repo — worth checking whether it fired for the 0.37.2 release.
• The homeassistant/ directory in this working tree is a stale pre-migration copy (0.36.3) of what now lives in the add-on repo. It is untracked, so it affects nobody, but it is a trap for anyone who finds it and assumes it is authoritative.

[matteius]

All remaining items are done, across 7cc881c, 2e33c91, d9a44b7 and 8042762. Every checkbox above is now checked; leaving the epic open briefly in case anything shakes out, then it can close.

What the Phase 0 sweep actually found. Script flags were all real — the suspicious-looking hits were journalctl invocations my grep mistook for lightnvr ones. The real breakage was elsewhere, and all of it was verified against the published 0.37.1 image rather than assumed:

• Docs described a web-asset copy-on-first-run from /usr/share/lightnvr/web-template/ to /var/lib/lightnvr/web/. Neither path exists; assets are baked in at /var/lib/lightnvr/www and the entrypoint verifies them ("no fallback copy"). This is now the warning it should always have been: never mount a volume over /var/lib/lightnvr.
• LIGHTNVR_AUTO_INIT and LIGHTNVR_WEB_ROOT are set by the image and docker-compose.yml but read by nothing. They were documented as working knobs.
• scripts/diagnose_web_issue.sh and scripts/build-ingenic.sh are both referenced by docs and have never existed in this repository's history.
• No .tar.gz release assets are published, only .deb — and the documented .deb URL omits the Debian suite the filenames carry, so it would 404.

Two things I deliberately did not do, both for the same reason — I could not verify them and would have been writing fiction:

1. Per-vendor NAS guides. Synology/QNAP/unRAID UIs change between versions and I have none of them to test against. Wrote one NAS section covering what is actually LightNVR-specific instead, and pointed at each vendor's own docs for the click-path.
2. A camera compatibility matrix. There are only 2–3 issues per vendor in the tracker — nowhere near enough to declare what works. CAMERAS.md instead teaches the reliable method for finding an RTSP URL and lists only real, linked, fixed issues. It will get better from reports, and the page says what a good report contains.

One inconsistency surfaced rather than papered over: scripts/release.sh creates tags as v$VERSION, but every release since 0.17 is tagged without the prefix. The publish workflow triggers on '*.*.*' so either works and nothing is broken — but the script and current practice disagree, and RELEASE_PROCESS.md's troubleshooting commands assume the script's form. Flagged inline in that document; worth a decision on which convention is intended.

Also worth noting: the link-check workflow failed on its own first run, in the success path — GitHub runs steps under bash -e and the step set pipefail, so a markdown file with zero links made grep exit 1 and killed it before it could report success. Rewritten as scripts/check_docs_links.py and verified against three negative cases plus a clean run.