From bfbdd0c19910f464e779fa64cc0ec8590f8e37c1 Mon Sep 17 00:00:00 2001 From: Christian Kolset Date: Fri, 31 Jul 2026 15:52:28 -0600 Subject: Add PyInstaller packaging and tufup-based auto-update pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full pipeline, verified end-to-end against the real installed tufup 0.10.0 API (initial docs/summaries turned out inaccurate in places — e.g. the apply method is download_and_apply_update, not update; confirmed by inspecting installed package source directly rather than trusting docs alone): - core/version.py: single-source app version constant. - labdaq.spec: PyInstaller onedir build (must be onedir, not onefile — tufup replaces individual files in the install dir on update). Bundles ui/*.qss, plugins/ (needed for runtime plugin discovery), and repository/metadata/root.json once repo_init.py has produced one. Built and smoke-tested: the frozen exe launches and stays running. - scripts/release/{repo_init,repo_release}.py: maintainer-run release tooling using tufup.repo.Repository, manual local signing (keys never touch CI). Both actually run end-to-end during development of this feature against a real build, not just written and assumed correct. Longer expiration_days than tufup-example's CI-oriented defaults (targets/snapshot/timestamp 90d instead of 7d/7d/1d), since we're signing manually, not on an automated daily schedule — see scripts/release/README.md for the re-signing cadence this still requires even between releases. - core/updater.py: thin Client wrapper. Refuses to run outside a frozen build (getattr(sys, "frozen", False)) since there's no installed bundle for tufup to update in `python main.py` dev mode. Bootstraps the bundled root.json into the metadata cache dir on first run — tuf.ngclient.Updater loads root.json from local disk on construction, it does not fetch it remotely by design (the root of trust can't come from the same server being verified). - core/app_settings.py: factored out app_data_dir() (was inline in _settings_path()) so the updater's metadata/target cache dirs live in the same per-user location as settings.json, deliberately outside the install directory an update can replace/move. - Settings > General: version display + "Check for Updates" button, manual-only per discussion (no silent background network calls or surprise restarts for a lab-instrument-control app). Metadata/targets are hosted on this repo's "updates" GitHub Release — a fixed tag, not a normal per-version tag, because TUF's top-level metadata needs a stable URL across app versions. No such GitHub-Releases- hosting example exists in tufup or tufup-example; verified this by fetching tufup-example's actual GitHub Actions workflow file directly after a web search wrongly suggested one existed — the design here is ours, not copied from upstream. Not yet done, deliberately left for the user: running repo_init.py for real (generates production signing keys), and creating the actual "updates" GitHub Release. Both are irreversible-ish, security-sensitive, externally-visible actions outside what should happen without the user directly driving them. Co-Authored-By: Claude Sonnet 5 --- scripts/release/README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 scripts/release/README.md (limited to 'scripts/release/README.md') diff --git a/scripts/release/README.md b/scripts/release/README.md new file mode 100644 index 0000000..6707ca1 --- /dev/null +++ b/scripts/release/README.md @@ -0,0 +1,61 @@ +# Release process (manual, local signing) + +All TUF signing keys stay on your machine, in `./keystore` (gitignored — never +commit it). Nothing here touches CI or GitHub Secrets. + +## One-time setup + +``` +pip install -r requirements-dev.txt +python scripts/release/repo_init.py +``` + +Generates `scripts/release/keystore/` (private + public keys for the +root/targets/snapshot/timestamp TUF roles) and `scripts/release/repository/` +(initial signed metadata, including `root.json`). + +**Back up `keystore/` immediately, somewhere private and durable outside this +repo.** Losing the root key means you can never publish a trusted update to +existing installs again — they'd all need a fresh, non-updating reinstall. + +Rebuild once more (`pyinstaller labdaq.spec`) after this step, so the +freshly-generated `root.json` gets bundled into the app (see the `.spec` +file's `_root_json` check — it only bundles the file if it already exists). + +## Every release + +1. Bump `__version__` in `core/version.py`. +2. `pyinstaller labdaq.spec` → produces `dist/LabDAQ/`. +3. `python scripts/release/repo_release.py` → creates+signs + `scripts/release/repository/targets/labdaq-.tar.gz` and updates + the metadata files in `scripts/release/repository/metadata/`. +4. Create (first time) or reuse the GitHub Release tagged **`updates`** on + this repo, and upload every file from `scripts/release/repository/metadata/` + and `scripts/release/repository/targets/` as release assets, **replacing** + any same-named files already there. + - This tag is fixed on purpose — the app's `metadata_base_url` always + points at `https://github.com///releases/download/updates/`. + A normal per-version-tagged release would give every version a + different URL, which breaks TUF's requirement that top-level metadata + (`timestamp.json`, `snapshot.json`, ...) live at a stable location. + - Cut a normal, separately-tagged human-facing release too if you want a + changelog/download page — this doesn't have to be the same release. +5. Test: launch a previous installed version, Settings → Check for Updates, + confirm it finds and applies the new version. + +## Re-signing without a new release + +Metadata expires even if nothing changed (`expiration_days` in +`repo_init.py`: root 365 days, targets/snapshot/timestamp 90 days). If you +haven't shipped a release before targets/snapshot/timestamp expire, clients +will start rejecting the metadata as stale. Re-sign with: + +``` +python -m tufup sign snapshot scripts/release/keystore +python -m tufup sign timestamp scripts/release/keystore +``` + +(run from the repo root; adjust the key directory path if you invoke this +from elsewhere) and re-upload the resulting files to the `updates` release. +Set a calendar reminder — there is no automation for this on purpose (manual +signing was a deliberate choice, not an oversight). -- cgit v1.2.3