Browse Source

docs(autoUpdater): document static storage strategy (#42755)

* docs: `autoUpdater` static storage strategy

* summary must be followed by newline

* lint: fix whitespace for code blocks

* lint: `js` -> `javascript`

* bump

* `javascript` -> `js`

* bump

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Erick Zhao <[email protected]>
trop[bot] 9 months ago
parent
commit
37fc8346aa
1 changed files with 112 additions and 0 deletions
  1. 112 0
      docs/tutorial/updates.md

+ 112 - 0
docs/tutorial/updates.md

@@ -10,6 +10,114 @@ The easiest and officially supported one is taking advantage of the built-in
 [Squirrel](https://github.com/Squirrel) framework and
 Electron's [autoUpdater](../api/auto-updater.md) module.
 
+## Using cloud object storage (serverless)
+
+For a simple serverless update flow, Electron's autoUpdater module can
+check if updates are available by pointing to a static storage URL
+containing latest release metadata.
+
+When a new release is available, this metadata needs to be published to
+cloud storage alongside the release itself. The metadata format is
+different for macOS and Windows.
+
+### Publishing release metadata
+
+With Electron Forge, you can set up static file storage updates by publishing
+metadata artifacts from the ZIP Maker (macOS) with `macUpdateManifestBaseUrl`
+and the Squirrel.Windows Maker (Windows) with `remoteReleases`.
+
+See Forge's [Auto updating from S3](https://www.electronforge.io/config/publishers/s3#auto-updating-from-s3)
+guide for an end-to-end example.
+
+<details>
+<summary>Manual publishing</summary>
+
+On macOS, Squirrel.Mac can receive updates by reading a `releases.json` file with the
+following JSON format:
+
+```json title='releases.json'
+{
+  "currentRelease": "1.2.3",
+  "releases": [
+    {
+      "version": "1.2.1",
+      "updateTo": {
+        "version": "1.2.1",
+        "pub_date": "2023-09-18T12:29:53+01:00",
+        "notes": "Theses are some release notes innit",
+        "name": "1.2.1",
+        "url": "https://mycompany.example.com/myapp/releases/myrelease"
+      }
+    },
+    {
+      "version": "1.2.3",
+      "updateTo": {
+        "version": "1.2.3",
+        "pub_date": "2024-09-18T12:29:53+01:00",
+        "notes": "Theses are some more release notes innit",
+        "name": "1.2.3",
+        "url": "https://mycompany.example.com/myapp/releases/myrelease3"
+      }
+    }
+  ]
+}
+```
+
+On Windows, Squirrel.Windows can receive updates by reading from the RELEASES
+file generated during the build process. This file details the `.nupkg` delta
+package to update to.
+
+```plaintext title='RELEASES'
+B0892F3C7AC91D72A6271FF36905FEF8FE993520 electron-fiddle-0.36.3-full.nupkg 103298365
+```
+
+These files should live in the same directory as your release, under a folder
+structure that is aware of your app's platform and architecture.
+
+For example:
+
+```plaintext
+my-app-updates/
+├─ darwin/
+│  ├─ x64/
+│  │  ├─ my-app-1.0.0-darwin-x64.zip
+│  │  ├─ my-app-1.1.0-darwin-x64.zip
+│  │  ├─ RELEASES.json
+│  ├─ arm64/
+│  │  ├─ my-app-1.0.0-darwin-arm64.zip
+│  │  ├─ my-app-1.1.0-darwin-arm64.zip
+│  │  ├─ RELEASES.json
+├─ win32/
+│  ├─ x64/
+│  │  ├─ my-app-1.0.0-win32-x64.exe
+│  │  ├─ my-app-1.0.0-win32-x64.nupkg
+│  │  ├─ my-app-1.1.0-win32-x64.exe
+│  │  ├─ my-app-1.1.0-win32-x64.nupkg
+│  │  ├─ RELEASES
+```
+
+</details>
+
+### Reading release metadata
+
+The easiest way to consume metadata is by installing [update-electron-app][],
+a drop-in Node.js module that sets up autoUpdater and prompts the user with
+a native dialog.
+
+For static storage updates, point the `updateSource.baseUrl` parameter to
+the directory containing your release metadata files.
+
+```js title="main.js" @ts-nocheck
+const { updateElectronApp, UpdateSourceType } = require('update-electron-app')
+
+updateElectronApp({
+  updateSource: {
+    type: UpdateSourceType.StaticStorage,
+    baseUrl: `https://my-bucket.s3.amazonaws.com/my-app-updates/${process.platform}/${process.arch}`
+  }
+})
+```
+
 ## Using update.electronjs.org
 
 The Electron team maintains [update.electronjs.org][], a free and open-source
@@ -151,6 +259,10 @@ server-communication aspect of the process by loading your update from a local d
 
 :::
 
+## Update server specification
+
+A Squirrel-compatible update server has different
+
 [vercel]: https://vercel.com
 [hazel]: https://github.com/vercel/hazel
 [nuts]: https://github.com/GitbookIO/nuts