bible-app/UPDATES.md

Updating the Bible App

The app updates itself from a source you control — the church's own Gitea server, a network share, a folder on this PC, or any small web server. No GitHub, no app store, nothing leaves the building.

---

One-time setup (per installed machine)

1. Open the app → menu (☰) → Settings → Updates

2. Put the update source in Update folder or address. The church's is:

   http://chronicles-ab.waterschurch.org:3000/api/packages/christian/generic/bible-app/latest
   

   Anything else the app accepts also works: \\WATERS-SERVER\builds\bible-app (network share), D:\BibleAppBuilds (folder on this PC), http://server.local/bible-app (web server).

3. Leave "Check for updates automatically when the app starts" ticked.

4. Click Save.

That's it. From now on the stage PC never needs a hand-carried .exe.

Checking is automatic; installing is not. With that box ticked the app asks the server at startup and remembers the answer, which Settings → Updates then shows. It never installs on its own — installing closes and reopens the app, so it stays a deliberate tap.

---

Installing an update (on the stage PC)

1. Settings → Updates → Check for Updates
2. If a new version exists it shows the version number and notes → Download & Install
3. A progress bar runs while the installer downloads (~750 MB, a couple of minutes over the LAN)
4. The app closes, the installer runs, and the app reopens

Everything is kept: notes, graphics, announcements, maps, annotations, service profiles, OSC settings, phone-remote PIN, and all popup/tool preferences. Those live in your user-content folder, which the installer never touches.

Do this before a service, not during one — the app restarts as part of installing.

---

Publishing a new version (on the laptop)

npm run release -- "Faster laser, new popup cards"
git commit -am "Release <version>" && git push

That bumps the patch version, builds the Windows installer, uploads it and a latest.json manifest to the update source, and clears out builds older than the previous one. The Windows installer builds on the Mac — see BUILD-AND-DEPLOY.md.

To publish an existing build, or to publish somewhere other than the default:

npm run publish-update                                        # newest build -> default target
npm run publish-update -- "\\WATERS-SERVER\builds\bible-app" "Notes"

Publish destination is chosen in this order:

1. the path or URL you pass on the command line
2. the BIBLEAPP_UPDATE_DIR environment variable
3. bibleApp.updateTarget in package.json (the church's Gitea registry)
4. the source configured in the app on this machine
5. dist-installer/publish (fallback)

Uploading to Gitea needs a token — GITEA_TOKEN, or the macOS keychain item gitea-mcp that the git tooling already uses. Downloading does not: the published installer is readable without a login, which is what lets the TV fetch it. The source repository stays private.

---

What latest.json looks like

The publish script writes it for you; you only need this if you're placing a build by hand:

{
  "version": "1.4.35",
  "file": "Bible App Setup 1.4.35.exe",
  "size": 784268993,
  "sha256": "7a628d27…",
  "notes": "What changed in this version",
  "date": "2026-09-24"
}

Both the .exe and latest.json must sit in the same place. Version numbers are compared numerically, so 1.4.10 correctly beats 1.4.9 — and the app only ever offers a HIGHER version, so re-publishing the same version number is invisible to it.

---

Setting up a brand-new machine — one file

Use Bible App Full Setup <version>.exe (about 2.7 GB). It is a single self-extracting file containing the app and the offline AI model. Copy it to the new PC any way you like (USB stick, network, cloud) and double-click it.

1. Windows asks for permission (it is an installer) → Yes
2. It asks "Install Bible App with the offline AI model?" → Yes
3. It installs the app and places the AI model. Nothing else to copy, no second file, no internet.

The AI model is written to C:\ProgramData\Bible App\llama-cache\model.gguf. That folder belongs to the machine, not to one user account, and no installer or update ever touches it — so the AI survives every future update. Settings → Updates will show "AI model installed for all users on this PC".

Why two different installers? A Windows installer cannot exceed 2 GB, and the app plus the model is over that. The regular Bible App Setup <version>.exe (~750 MB) is what the in-app updater downloads. The Full one exists for new machines.

Always check the file after copying it. An interrupted copy or a cloud placeholder leaves a 0 KB file, and Windows then says "This app can't run on your PC" — which looks like an app problem but isn't:

Get-FileHash "Bible App Full Setup 1.4.35.exe" -Algorithm SHA256

Compare that to the .sha256 file next to the installer. If they match, install it. If not (or the file is 0 KB), copy it again.

After that first install, updates verify themselves — the app checks size and checksum before it runs anything, and refuses a damaged download instead of installing it.

Keeping several machines in step

Point every machine at the same update source and nobody hand-carries files again. The Gitea URL above works from anywhere on the church network; a network share or a web address works too.

If something goes wrong

Symptom	Fix
"Could not read update info"	The address is wrong, or latest.json isn't there. Check Settings → Updates, and that the machine can reach the Gitea server.
"Installer not found"	latest.json's file name doesn't match the actual .exe. Re-run npm run publish-update.
Network share not reachable	Confirm the stage PC can open that share in File Explorer.
Update seems stuck	The installer is large; watch the progress bar. It resumes fine if you retry.
"came across empty (0 bytes)" / "is incomplete"	The transfer didn't finish. Publish again and retry.
"was damaged in transfer (checksum mismatch)"	The file arrived corrupted. Publish or copy it again.
Windows: "This app can't run on your PC"	The .exe is 0 KB, corrupt, or the wrong architecture — check its size and verify the hash.
Need to roll back	git checkout v<older> and npm run release -- --no-bump "Rolling back", or run the previous installer (still in the update source) by hand — it installs over the top.