Build and release
Targets: Linux x64 (AppImage + unpacked) and Windows x64 (NSIS installer + unpacked). No macOS.
Packaging configuration (electron-builder.yml)
files:out/**andpackage.jsononly.asarUnpack:libsql,@libsqland7zip-bin(native binaries cannot run from inside the asar). Per-platformfilesfilters drop the other platforms’ native packages.extraResources:drizzle/(migrations) andresources/.npmRebuild: false: libsql ships prebuilt binaries as per-platform optional dependencies.
Local builds
npm run build:linux # AppImage + dist/linux-unpackednpm run build:win # Windows installer, built on Linux through wine in Dockernpm run build:allscripts/ensure-native-targets.mjsinstalls the other platform’s@libsql/*package with--no-save --force(npm only installs the host’s optional dependencies). Rerun after a cleannpm install; it is part of thebuild:*scripts.scripts/build-win-docker.shrunselectron-builder --wininsideelectronuserland/builder:winewith a cache volume (bakasub-ebcache).
Icons
resources/icon.svg is the only source. npm run icons (scripts/build-icons.sh, needs librsvg and ImageMagick) regenerates resources/icon.png (512 px, the Linux window icon: Electron’s nativeImage cannot read SVG), build/icon.png (1024 px) and build/icon.ico (16–256 px) for electron-builder (buildResources: build). The renderer’s sidebar logo is src/renderer/src/assets/logo.svg; the README banners are docs/bakasub-logo-{en,pt}.svg.
CI (.github/workflows/release.yml)
Triggers: v* tags and workflow_dispatch (artifacts only, no release).
buildmatrix (ubuntu-latest,windows-latest): verify tag ==package.jsonversion,npm ci, ESLint,npm test(vitest),db:check,npm run dist:linux|dist:win, smoke test, packaging.- Smoke test: start the unpacked binary for ~20 s and require
database readyinuserData/logs/main.log(proves libsql + migrations on the real OS). - A step validates
manifests/**with the app’s own Zod schema (manifest.schema.test.ts). releasejob: verify the artifacts (including the updater metadata) exist, generateSHA256SUMS.txt,gh release create --draft(pre-release when the tag contains-).
Artifacts: bakasub-<v>.AppImage, bakasub-<v>-linux-x64-unpacked.tar.gz, bakasub-<v>-setup.exe, bakasub-<v>-win-x64-unpacked.zip, SHA256SUMS.txt, and the updater files latest.yml (Windows), latest-linux.yml and the installer’s *.blockmap (the AppImage’s blockmap is embedded, there is no separate file).
Auto-update (electron-updater)
electron-builder.yml has a publish block (GitHub, lsilvatti/bakasub), which makes electron-builder embed app-update.yml in the build and generate latest.yml/latest-linux.yml (sha512 of the installer + blockmap for differential downloads). CI keeps --publish never and attaches those files to the release itself.
Flow: tag vX.Y.Z → CI creates a draft → review → publish the draft by hand. Publishing is the “go” of the update: the updater only sees published, non-pre-release releases (allowPrerelease = false), so a draft never reaches users. The Main only checks (silently once, AUTO_CHECK_DELAY_MS = 3 s after the window is created, unless updates.autoCheck is off, or on demand; a new version opens the renderer’s update dialog); it downloads on app:download-update and restarts on app:install-update. See the contract in ipc.md.
Limitations:
- Windows (NSIS) updates work without code signing as long as
publisherNameis not configured (electron-updater would otherwise compare the signature). SmartScreen still warns on the first manual download. - Linux only updates when running as an AppImage (
process.env.APPIMAGE). Dev builds,linux-unpackedand an AppImage launched without that variable reportunsupportedwithfallbackUrl(the releases page). - macOS, signing/notarization, beta channel and downgrade are out of scope.
- User data (database,
userData/bin, settings) lives inuserData, which the installer never touches.
Testing an update end to end
- Publish a release
vN(e.g. 1.0.0) and install it (Windows installer or AppImage). - Bump
package.jsontovN+1, tag, wait for the draft, publish it. - In the installed app (
vN):app:check-update→available;app:download-update→downloaded;app:install-update→ relaunches asvN+1. Also try it with a job running (expectUPDATE_JOBS_ACTIVE, thenconfirmJobs: true). - Logs:
userData/logs/main.log(scopeapp).
Releasing a version
- Work on
mainwith a clean tree. Locally:npm run lint,npm run typecheck,npm test,npm run db:check, and a manual pass throughnpm run dev(onboarding, one translation, extract, mux). - If the schema changed,
npm run db:generateand commit the migration indrizzle/. - Bump
versioninpackage.json(andpackage-lock.json):npm version <x.y.z> --no-git-tag-version. The tag must equal this version or CI fails on the first step. - Commit (
chore(release): vX.Y.Z) and push tomain. - Optional dry run: run the Release workflow by hand (
workflow_dispatch) and download the artifacts; no release is created. - Tag and push:
git tag vX.Y.Z && git push origin vX.Y.Z. A tag with-(e.g.v1.1.0-rc.1) creates a pre-release, which the updater ignores. - CI builds Linux and Windows, runs the smoke tests and creates a draft release with the artifacts,
SHA256SUMS.txtand the updater metadata. - Open the draft on GitHub, check the artifacts and edit the generated notes, then publish. From this moment installed apps see the update.
- If a published release is bad, mark it as a draft again (or delete it) so the updater stops offering it, and ship a fixed patch version. Never reuse a tag.
Caveats
linux-unpackedneeds--no-sandboxor a setuidchrome-sandbox(chown root+chmod 4755).- Validate the Windows NSIS update and the AppImage self-replace on real hardware before relying on them (unit tests mock
electron-updater). Use the procedure above with a throwawayvN+1. - Binaries are unsigned. Actions are pinned by major tag, not by commit SHA.
- Hosting sidecar binaries yourself would make you their distributor (GPL/LGPL source obligations); the current design only stores URLs and checksums.