docs(autoUpdater): document static storage strategy (#42690)
* docs: `autoUpdater` static storage strategy * summary must be followed by newline * lint: fix whitespace for code blocks * lint: `js` -> `javascript` * bump * `javascript` -> `js` * bump
This commit is contained in:
Erick Zhao
GitHub
parent
6cca75ac76
commit
0a8eae9019
1 changed files with 112 additions and 0 deletions
|
|
@ -10,6 +10,114 @@ The easiest and officially supported one is taking advantage of the built-in
|
||||||
[Squirrel](https://github.com/Squirrel) framework and
|
[Squirrel](https://github.com/Squirrel) framework and
|
||||||
Electron's [autoUpdater](../api/auto-updater.md) module.
|
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
|
## Using update.electronjs.org
|
||||||
|
|
||||||
The Electron team maintains [update.electronjs.org][], a free and open-source
|
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
|
[vercel]: https://vercel.com
|
||||||
[hazel]: https://github.com/vercel/hazel
|
[hazel]: https://github.com/vercel/hazel
|
||||||
[nuts]: https://github.com/GitbookIO/nuts
|
[nuts]: https://github.com/GitbookIO/nuts
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue