bible-app/BUILD-AND-DEPLOY.md

Bible App — build on the laptop, push to git, update the TVs remotely

This folder is the complete source tree of the Bible App as it runs on the stage TV (version in package.json). Everything the installer build needs is here. Nothing the build produces is.

1. What is (and is not) in this folder

Included — everything the build and the app need:

• All sources: app.js, server.js, main.cjs, preload.cjs, init.js, the *.html pages, styles.css, every additive module (follower-*.js, tool-wheel.js, propresenter-*.js, quick-dock.js, …).
• App data: Translations/, the *_bible.json files, nlt-data.js, interlinear/, Dictionary/ (JSON), dict/, fonts/, Notes/, Announcements/, Graphics/ (the defaults that ship inside the installer).
• Vendored runtimes that ship inside the installer: vendor/whisper, vendor/upscale, vendor/redist, vendor/llama (the llama-server binaries — NOT the models), vendor/fontawesome.
• Build inputs: package.json, package-lock.json, build/installer.nsh, tools/ (build-full-installer.cjs, publish-update.cjs, the SFX stub in tools/sfx, mock-propresenter.cjs), build-installer.bat.
• The *.md notes at the root (small; project history worth keeping).

Left out on purpose (would only take space):

Left out	Why
dist-installer/ (57 GB), dist/	every old installer ever built; the build recreates them
.git/ (32 GB)	the old history had installers and models committed into it — start a fresh repo (below)
node_modules/ (640 MB)	npm ci recreates it exactly from package-lock.json
vendor/llama/*.gguf (8 GB)	AI models; the regular installer never carries them (see §5)
.ebcache/, archive/, *.log, server-port.txt	build cache, retired scratch files, runtime files
Dictionary/**/*.zip, the Strong's XML folder	source archives; the app reads the converted JSON beside them

Size of this folder: about 1.3 GB, of which ~700 MB is the vendored runtimes and ~400 MB is Bible data.

2. Build machine prerequisites (the laptop)

• Windows 10/11 x64.
• Node.js 22 LTS (this tree was built with Node 22.18 / npm 10.9). Install from nodejs.org.
• Internet the first time: npm ci downloads Electron and electron-builder pulls NSIS and its winCodeSign helper into %LOCALAPPDATA%\electron-builder\Cache (a few hundred MB, once).
• No code-signing certificate is used. The build must be told so (step 3).

3. Build the regular installer

cd bible-app-source
npm ci
set CSC_IDENTITY_AUTO_DISCOVERY=false
npx electron-builder --win

Output: dist-installer\Bible App Setup <version>.exe (about 750 MB).

Notes:

• Bump "version" in package.json before every build you intend to ship. The TV's updater compares versions numerically and only offers a HIGHER version.
• build-installer.bat does the same as the commands above and also bumps the patch version and clears the electron-builder cache first. Either way works.
• If WIN_CSC_LINK / CSC_LINK / CSC_KEY_PASSWORD / CSC_KEYCHAIN exist in your environment they must be REMOVED, not set to empty — electron-builder aborts on an empty WIN_CSC_LINK ("Env WIN_CSC_LINK is not correct"). In PowerShell: Remove-Item Env:WIN_CSC_LINK.
• If the build fails while extracting winCodeSign (symlink / permission errors), run the terminal as administrator or turn on Windows Developer Mode, delete %LOCALAPPDATA%\electron-builder\Cache\winCodeSign, and build again.

4. Update the TVs remotely (no cable, no remote desktop)

Each TV has Settings › Updates › "Update folder or address" — a network share (\\SERVER\share\bible-app), a folder, or an http:// address — plus "Check for updates automatically when the app starts". The TV reads <source>/latest.json there, compares versions, then downloads and runs the installer. The app closes, installs, reopens; notes, graphics, annotations and settings are kept.

From the laptop, after a build:

npm run publish-update -- "\\SERVER\share\bible-app" "what changed in this version"

That copies the newest installer into the folder and writes latest.json (version, file name, size, sha256, notes). For an http:// source, upload the .exe and latest.json to the web server yourself. npm run release builds and publishes in one go.

The TV picks the update up at its next start (auto-check on) or when someone taps Check for Updates in Settings. It never installs without that check, so time the publish for after the service.

5. Full Setup (only for a brand-new machine)

A machine that has never had the app needs the AI model once (about 1.9 GB). That is the one-file "Bible App Full Setup", which drops the model into %ProgramData%\Bible App\llama-cache where updates never touch it. To build it, put the model at vendor/llama/model.gguf (exactly 2,019,377,696 bytes — copy it from the stage PC: C:\Users\media\Downloads\bible-app\vendor\llama\model.gguf or C:\ProgramData\Bible App\llama-cache\model.gguf; it is gitignored, so it never enters the repo), build the regular installer, then:

node tools/build-full-installer.cjs

Machines that already have the model keep using the regular installer.

6. Put it in git

cd bible-app-source
git init
git add -A
git commit -m "Bible App <version> — full source"
git remote add origin <your local git server URL>
git push -u origin main

.gitignore keeps the build outputs, node_modules, models and logs out; .gitattributes stores every file byte-for-byte (the sources are CRLF, and several maintenance scripts match CRLF exactly).

The first push is about 1.3 GB, mostly the vendored runtimes and Bible JSON. A local Gitea / GitLab handles that fine; if your server has Git LFS enabled, the commented lines in .gitattributes move the vendor/ binaries into LFS (only do that with LFS actually on, or clones get pointer files).

7. Dev-run without building

npm ci
node server.js

then open http://localhost:8080/. To run a test copy beside a live app, set BIBLE_APP_PORT=8095 and BIBLE_APP_DATA_DIR=<some scratch folder> so it never touches the church's real content in %APPDATA%\Bible App.