diff --git a/docs/README.md b/docs/README.md index be476c3..729398f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,7 @@ docs/ │ ├── api-endpoints.md │ ├── configuration-reference.md │ ├── database-schema.md +│ ├── desktop-build-and-distribution.md │ ├── memory-coordination-prompt.md │ └── skillsmith.md │ @@ -65,3 +66,4 @@ docs/ - [Testing](testing-reference.md) - [Data Contracts](domains/data-contracts-reference.md) - [User Workflows](product/user-workflows-reference.md) +- [Desktop Build & Distribution](reference/desktop-build-and-distribution.md) diff --git a/docs/docs-index.yaml b/docs/docs-index.yaml index fc6899f..6fea22e 100644 --- a/docs/docs-index.yaml +++ b/docs/docs-index.yaml @@ -186,6 +186,6 @@ docs_index: tags: [releases, desktop, electron, windows, linux, macos, installers] anchors: - id: ci - summary: "Desktop installers workflow: manual or on v* tag; download .exe, .deb, .dmg" + summary: "Desktop installers workflow: manual or on v* tag; artifacts + release flow; unsigned-by-default signing status and troubleshooting" depends_on: [doc.releases-distribution] - last_verified: "2026-03-06" + last_verified: "2026-03-09" diff --git a/docs/reference/desktop-build-and-distribution.md b/docs/reference/desktop-build-and-distribution.md index 84b18a3..1a4a221 100644 --- a/docs/reference/desktop-build-and-distribution.md +++ b/docs/reference/desktop-build-and-distribution.md @@ -1,6 +1,6 @@ # Desktop build and distribution -How to produce signed/notarized Windows (.exe), Linux (.deb), and macOS (.dmg) installers and enable auto-updates from GitHub Releases. +How Dossier currently produces desktop installers (Windows `.exe`, Linux `.deb`, macOS `.dmg`) and publishes them for update checks. ## Artifact formats @@ -12,6 +12,36 @@ How to produce signed/notarized Windows (.exe), Linux (.deb), and macOS (.dmg) i Version `X.Y.Z` comes from `package.json` `version`. +## Current behavior (as implemented) + +The source of truth is: + +- `.github/workflows/desktop-build.yml` +- `package.json` (`electron:make`) +- `forge.config.js` +- `electron/main.ts` (`updateElectronApp`) + +### What CI does today + +- Builds installers on three runners (`ubuntu-latest`, `windows-latest`, `macos-latest`). +- Uses `pnpm install --frozen-lockfile`. +- Runs `pnpm run electron:make`, which runs: + 1. `pnpm run build` + 2. `pnpm run electron:prepare-node` + 3. `pnpm run electron:compile` + 4. `electron-forge make` +- Uploads each runner's `out/make/` as an artifact. +- Creates a GitHub Release only for `v*` tag pushes. + +### Signing/notarization status + +Signing and notarization are currently **disabled by default** in source: + +- CI signing env and prep steps are commented out in `.github/workflows/desktop-build.yml`. +- Forge signing/notarization options are commented out in `forge.config.js`. + +Result: default CI outputs are unsigned installers unless signing is explicitly re-enabled in code. + ## Auto-update The app uses [update.electronjs.org](https://update.electronjs.org) (free for open-source apps on GitHub). When you create a **GitHub Release** with the built installers: @@ -21,9 +51,12 @@ The app uses [update.electronjs.org](https://update.electronjs.org) (free for op **To enable auto-update:** Push a version tag (e.g. `v0.5.3`) so the workflow runs. The **release** job creates a GitHub Release and attaches the Windows, Linux, and macOS artifacts. Ensure `package.json` `version` matches the tag (e.g. `0.5.3` for tag `v0.5.3`). -## Signing and notarization +## Signing and notarization (prepared, currently disabled) -When the following **repository secrets** are set, the CI build signs and (on macOS) notarizes the installers. If secrets are missing, builds still run but produce **unsigned** installers (fine for local/testing; stores and auto-update on macOS prefer signed/notarized). +The workflow and Forge config include commented templates for signing/notarization. If you decide to enable them, use the following secrets and uncomment the corresponding blocks in: + +- `.github/workflows/desktop-build.yml` +- `forge.config.js` ### macOS (code sign + notarization) @@ -45,7 +78,7 @@ Choose **one** of these two methods. | `APPLE_API_ISSUER` | Issuer UUID from App Store Connect → Users and Access → Integrations → API Keys | | `APPLE_API_KEY_BASE64` | Base64-encoded contents of your `.p8` key file (download from App Store Connect; only available once) | -The workflow decodes this to a temporary file and sets `APPLE_API_KEY_PATH` before the build. Do not commit the `.p8` file. +The template workflow decodes this to a temporary file and sets `APPLE_API_KEY_PATH` before the build. Do not commit the `.p8` file. ### Windows (Squirrel code signing) @@ -54,12 +87,7 @@ The workflow decodes this to a temporary file and sets `APPLE_API_KEY_PATH` befo | `WINDOWS_CERTIFICATE_PFX_BASE64` | Base64-encoded `.pfx` (or `.p12`) code signing certificate | | `WINDOWS_CERTIFICATE_PASSWORD` | Password for the PFX | -The workflow decodes the base64 to `cert.pfx` on the Windows runner before building. Do not commit `cert.pfx`; it is in `.gitignore`. - -### Local signed builds - -- **macOS:** Set `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID` (or the API key vars) in your environment and run `pnpm run electron:make` on a Mac. Signing and notarization run automatically when credentials are present. -- **Windows:** Put your `.pfx` at the repo root as `cert.pfx` (or set `certificateFile` in `forge.config.js`), set `WINDOWS_CERTIFICATE_PASSWORD`, and run `pnpm run electron:make` on Windows. For CI we use base64 + secret instead of a committed file. +The template workflow decodes the base64 to `cert.pfx` on the Windows runner before building. Do not commit `cert.pfx`; it is in `.gitignore`. ## Building on demand (CI) @@ -74,18 +102,53 @@ The **Desktop installers** workflow builds all three platforms and (on tag push) - Download `dossier-windows-`, `dossier-linux-`, `dossier-macos-`. - For tagged runs, the same files are attached to the GitHub Release. -3. **Use for stores** - - Attach the installer files from the release (or artifacts) to your web site or app store submission. Signing/notarization is applied when the secrets above are set. +3. **Use for distribution** + - Attach installer files from artifacts/release to your website or release process. + - If you need signed/notarized builds, enable signing in workflow + Forge first (see section above). ## Building locally Electron Forge only produces installers for the **current OS** (no cross-compilation). -- **macOS:** `pnpm run electron:make` → `out/make/*.dmg` (signed/notarized if Apple env vars are set). -- **Windows:** Same command on Windows → `out/make/*.exe` (+ Squirrel artifacts; signed if `cert.pfx` and password are set). +- **macOS:** `pnpm run electron:make` → `out/make/*.dmg`. +- **Windows:** Same command on Windows → `out/make/*.exe` (+ Squirrel artifacts). - **Linux:** Same command on Linux → `out/make/*.deb`. -To get all three from one place, use the CI workflow. +By default, local outputs are unsigned because signing/notarization config is commented out in `forge.config.js`. + +To get all three platforms from one place, use the CI workflow. + +## Troubleshooting and common pitfalls + +### Linux `.deb` maker fails on CI + +Symptom: Debian packaging step fails on Ubuntu runners. + +Cause: `fakeroot` missing. + +Current fix in workflow: Ubuntu job installs `fakeroot` before `electron:make`. + +### Windows build exits with heap/OOM errors + +Symptom: `electron:make` fails on Windows runner with memory-related errors. + +Cause: Windows builds may require higher Node heap. Also, setting `NODE_OPTIONS` via `GITHUB_ENV` is blocked by GitHub Actions. + +Current fix in workflow: set `NODE_OPTIONS=--max-old-space-size=4096` only on the **Build desktop installers** step for Windows. + +### Tag pushed but release artifacts mismatch + +Symptom: release job cannot find artifacts (download step fails). + +Cause: release job expects artifacts named with the version extracted from `refs/tags/v*`. If the tag/version flow is inconsistent, names can diverge. + +Check: + +- `package.json` version matches tag (`0.5.2` -> `v0.5.2`) +- build artifacts exist: + - `dossier-windows-` + - `dossier-linux-` + - `dossier-macos-` ## Configuration