From 823e7714e05b519d8c16dbbc79202baefc124088 Mon Sep 17 00:00:00 2001 From: Werner Robitza Date: Fri, 26 Apr 2024 09:06:52 +0200 Subject: [PATCH] docs: explain auto-updates better --- docs/auto-update.md | 104 ++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 46 deletions(-) diff --git a/docs/auto-update.md b/docs/auto-update.md index 667ce79cacf..354d946d1bf 100644 --- a/docs/auto-update.md +++ b/docs/auto-update.md @@ -1,4 +1,12 @@ -See [publish configuration](configuration/publish.md) for information on how to configure your local or CI environment for automated deployments. +Auto updates are enabled by the `electron-updater` package. Ideally, auto updates are configured to run in a CI pipeline to automatically provision new releases. See [publish configuration](configuration/publish.md) for information on how to configure your local or CI environment for automated deployments. + +Auto updates work as follows: + +- You configure the package to build release metadata (`latest.yml`) +- Electron builder uploads the actual release targets and metadata files to the configured target (except for generic server, where you have to upload manually) +- You configure the Electron application to use auto-updates, which queries the publish server for possible new releases + +Read the remainder of this guide to configure everything. !!! info "Code signing is required on macOS" macOS application must be [signed](code-signing.md) in order for auto updating to work. @@ -17,21 +25,25 @@ All these targets are default, custom configuration is not required. (Though it ## Differences between electron-updater and built-in autoUpdater -* Dedicated release server is not required. +The `electron-updater` package offers a different functionality compared to Electron's built-in auto-updater. Here are the differences: + +* A dedicated release server is not required. * Code signature validation not only on macOS, but also on Windows. * All required metadata files and artifacts are produced and published automatically. * Download progress and [staged rollouts](#staged-rollouts) supported on all platforms. -* Different providers supported out of the box ([GitHub Releases](https://help.github.com/articles/about-releases/), [Amazon S3](https://aws.amazon.com/s3/), [DigitalOcean Spaces](https://www.digitalocean.com/community/tutorials/an-introduction-to-digitalocean-spaces), [Keygen](https://keygen.sh/docs/api/#auto-updates-electron) and generic HTTP(s) server). +* Different providers supported out of the box: ([GitHub Releases](https://help.github.com/articles/about-releases/), [Amazon S3](https://aws.amazon.com/s3/), [DigitalOcean Spaces](https://www.digitalocean.com/community/tutorials/an-introduction-to-digitalocean-spaces), [Keygen](https://keygen.sh/docs/api/#auto-updates-electron) and generic HTTP(s) server). * You need only 2 lines of code to make it work. ## Quick Setup Guide 1. Install [electron-updater](https://yarn.pm/electron-updater) as an app dependency. -2. [Configure publish](configuration/publish.md). +2. Configure the [`publish`](configuration/publish.md) options depending on where you want to host your release files. + +3. Build your application and check that the build directory contains the metadata `.yml` files next to the built application. For most publish targets, the building step will also upload the files, except for the generic server option, where you have to upload your built releases and metadata manually. + +4. Use `autoUpdater` from `electron-updater` instead of `electron`: -3. Use `autoUpdater` from `electron-updater` instead of `electron`: - JavaScript ```js const { autoUpdater } = require("electron-updater") @@ -49,10 +61,10 @@ All these targets are default, custom configuration is not required. (Though it // It is a workaround for ESM compatibility issues, see https://github.com/electron-userland/electron-builder/issues/7976. const { autoUpdater } = electronUpdater; return autoUpdater; - } + } ``` -4. Call `autoUpdater.checkForUpdatesAndNotify()`. Or, if you need custom behaviour, implement `electron-updater` events, check examples below. +5. Call `autoUpdater.checkForUpdatesAndNotify()`. Or, if you need custom behaviour, implement `electron-updater` events, check examples below. !!! note 1. Do not call [setFeedURL](#appupdatersetfeedurloptions). electron-builder automatically creates `app-update.yml` file for you on build in the `resources` (this file is internal, you don't need to be aware of it). @@ -344,14 +356,14 @@ Emitted on progress. ### `BaseS3Options` ⇐ [PublishConfiguration](electron-builder#PublishConfiguration) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * channel = `latest` String | "undefined" - The update channel. * path = `/` String | "undefined" - The directory path. * acl = `public-read` "private" | "public-read" | "undefined" - The ACL. Set to `null` to not [add](https://github.com/electron-userland/electron-builder/issues/1822). * **provider** "github" | "bintray" | "s3" | "spaces" | "generic" | "custom" | "snapStore" | "keygen" - The provider. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -361,7 +373,7 @@ Emitted on progress. Define `BT_TOKEN` environment variable. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "bintray" - The provider. Must be `bintray`. * package String | "undefined" - The Bintray package name. @@ -372,7 +384,7 @@ Define `BT_TOKEN` environment variable. * user String | "undefined" - The Bintray user account. Used in cases where the owner is an organization. * token String | "undefined" * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -395,12 +407,12 @@ Define `BT_TOKEN` environment variable. ### `CustomPublishOptions` ⇐ [PublishConfiguration](electron-builder#PublishConfiguration) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "custom" - The provider. Must be `custom`. * updateProvider module:builder-util-runtime/out/publishOptions.__type - The Provider to provide UpdateInfo regarding available updates. Required to use custom providers with electron-updater. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -420,14 +432,14 @@ Generic (any HTTP(S) server) options. In all publish options [File Macros](/file-patterns#file-macros) are supported. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "generic" - The provider. Must be `generic`. * **url** String - The base url. e.g. `https://bucket_name.s3.amazonaws.com`. * channel = `latest` String | "undefined" - The channel. * useMultipleRangeRequest Boolean - Whether to use multiple range requests for differential update. Defaults to `true` if `url` doesn't contain `s3.amazonaws.com`. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -439,7 +451,7 @@ GitHub [personal access token](https://help.github.com/articles/creating-an-acce Define `GH_TOKEN` environment variable. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "github" - The provider. Must be `github`. * repo String | "undefined" - The repository name. [Detected automatically](#github-repository-and-bintray-package). @@ -450,10 +462,10 @@ Define `GH_TOKEN` environment variable. * token String | "undefined" - The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for [setFeedURL](/auto-update#appupdatersetfeedurloptions). * private Boolean | "undefined" - Whether to use private github auto-update provider if `GH_TOKEN` environment variable is defined. See [Private GitHub Update Repo](/auto-update#private-github-update-repo). * releaseType = `draft` "draft" | "prerelease" | "release" | "undefined" - The type of release. By default `draft` release will be created. - + Also you can set release type using environment variable. If `EP_DRAFT`is set to `true` — `draft`, if `EP_PRE_RELEASE`is set to `true` — `prerelease`. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -464,7 +476,7 @@ https://keygen.sh/ Define `KEYGEN_TOKEN` environment variable. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "keygen" - The provider. Must be `keygen`. * **account** String - Keygen account's UUID @@ -472,14 +484,14 @@ Define `KEYGEN_TOKEN` environment variable. * channel = `stable` "stable" | "rc" | "beta" | "alpha" | "dev" | "undefined" - The channel. * platform String | "undefined" - The target Platform. Is set programmatically explicitly during publishing. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers ### `PackageFileInfo` ⇐ [BlockMapDataHolder](#BlockMapDataHolder) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [BlockMapDataHolder](#BlockMapDataHolder) +**Extends**: [BlockMapDataHolder](#BlockMapDataHolder) **Properties** * **path** String @@ -499,7 +511,7 @@ Define `KEYGEN_TOKEN` environment variable. **Properties** * **provider** "github" | "bintray" | "s3" | "spaces" | "generic" | "custom" | "snapStore" | "keygen" - The provider. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -513,17 +525,17 @@ Define `KEYGEN_TOKEN` environment variable. ### `RequestHeaders` ⇐ [key: string]: OutgoingHttpHeader | undefined **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [key: string]: OutgoingHttpHeader | undefined +**Extends**: [key: string]: OutgoingHttpHeader | undefined ### `S3Options` ⇐ [BaseS3Options](electron-builder#BaseS3Options) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [BaseS3Options](electron-builder#BaseS3Options) +**Extends**: [BaseS3Options](electron-builder#BaseS3Options) **Properties** * **provider** "s3" - The provider. Must be `s3`. * **bucket** String - The bucket name. * region String | "undefined" - The region. Is determined and set automatically when publishing. * acl = `public-read` "private" | "public-read" | "undefined" - The ACL. Set to `null` to not [add](https://github.com/electron-userland/electron-builder/issues/1822). - + Please see [required permissions for the S3 provider](https://github.com/electron-userland/electron-builder/issues/1618#issuecomment-314679128). * storageClass = `STANDARD` "STANDARD" | "REDUCED_REDUNDANCY" | "STANDARD_IA" | "undefined" - The type of storage to use for the object. * encryption "AES256" | "aws:kms" | "undefined" - Server-side encryption algorithm to use for the object. @@ -534,13 +546,13 @@ Define `KEYGEN_TOKEN` environment variable. [Snap Store](https://snapcraft.io/) options. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) +**Extends**: [PublishConfiguration](electron-builder#PublishConfiguration) **Properties** * **provider** "snapStore" - The provider. Must be `snapStore`. * **repo** String - snapcraft repo name * channels = `["edge"]` String | Array<String> | "undefined" - The list of channels the snap would be released. * publishAutoUpdate = `true` Boolean - Whether to publish auto update info files. - + Auto update relies only on the first provider in the list (you can specify several publishers). Thus, probably, there`s no need to upload the metadata files for the other configured providers. But by default will be uploaded. * requestHeaders [key: string]: string - Any custom request headers @@ -550,7 +562,7 @@ Define `KEYGEN_TOKEN` environment variable. Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment variables. **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [BaseS3Options](electron-builder#BaseS3Options) +**Extends**: [BaseS3Options](electron-builder#BaseS3Options) **Properties** * **provider** "spaces" - The provider. Must be `spaces`. * **name** String - The space name. @@ -559,7 +571,7 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### `UpdateFileInfo` ⇐ [BlockMapDataHolder](#BlockMapDataHolder) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [BlockMapDataHolder](#BlockMapDataHolder) +**Extends**: [BlockMapDataHolder](#BlockMapDataHolder) **Properties** * **url** String @@ -579,18 +591,18 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### `WindowsUpdateInfo` ⇐ [UpdateInfo](#UpdateInfo) **Kind**: interface of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: [UpdateInfo](#UpdateInfo) +**Extends**: [UpdateInfo](#UpdateInfo) **Properties** * packages Object<String, any> | "undefined" ### CancellationError ⇐ Error **Kind**: class of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: Error +**Extends**: Error ### CancellationToken ⇐ module:events.EventEmitter **Kind**: class of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: module:events.EventEmitter +**Extends**: module:events.EventEmitter **Properties** * **cancelled** Boolean @@ -612,7 +624,7 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### DigestTransform ⇐ internal:Transform **Kind**: class of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: internal:Transform +**Extends**: internal:Transform **Properties** * actual String * isValidateOnEnd = `true` Boolean @@ -640,7 +652,7 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### HttpError ⇐ Error **Kind**: class of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: Error +**Extends**: Error #### `httpError.isServerError()` ⇒ Boolean @@ -704,7 +716,7 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### ProgressCallbackTransform ⇐ internal:Transform **Kind**: class of [builder-util-runtime](#module_builder-util-runtime)
-**Extends**: internal:Transform +**Extends**: internal:Transform * [.ProgressCallbackTransform](#ProgressCallbackTransform) ⇐ internal:Transform * [`._flush(callback)`](#module_builder-util-runtime.ProgressCallbackTransform+_flush) @@ -986,29 +998,29 @@ Access key is required, define `DO_KEY_ID` and `DO_SECRET_KEY` environment varia ### `UpdateDownloadedEvent` ⇐ module:builder-util-runtime.UpdateInfo **Kind**: interface of [electron-updater](#module_electron-updater)
-**Extends**: module:builder-util-runtime.UpdateInfo +**Extends**: module:builder-util-runtime.UpdateInfo **Properties** * **downloadedFile** String ### AppImageUpdater ⇐ module:electron-updater/out/BaseUpdater.BaseUpdater **Kind**: class of [electron-updater](#module_electron-updater)
-**Extends**: module:electron-updater/out/BaseUpdater.BaseUpdater +**Extends**: module:electron-updater/out/BaseUpdater.BaseUpdater #### `appImageUpdater.isUpdaterActive()` ⇒ Boolean ### AppUpdater ⇐ module:events.EventEmitter **Kind**: class of [electron-updater](#module_electron-updater)
-**Extends**: module:events.EventEmitter +**Extends**: module:events.EventEmitter **Properties** * autoDownload = `true` Boolean - Whether to automatically download an update when it is found. * autoInstallOnAppQuit = `true` Boolean - Whether to automatically install a downloaded update on app quit (if `quitAndInstall` was not called before). * allowPrerelease = `false` Boolean - *GitHub provider only.* Whether to allow update to pre-release versions. Defaults to `true` if application version contains prerelease components (e.g. `0.12.1-alpha.1`, here `alpha` is a prerelease component), otherwise `false`. - + If `true`, downgrade will be allowed (`allowDowngrade` will be set to `true`). * fullChangelog = `false` Boolean - *GitHub provider only.* Get all release notes (from current version to latest), not just the latest. * allowDowngrade = `false` Boolean - Whether to allow version downgrade (when a user from the beta channel wants to go back to the stable channel). - + Taken in account only if channel differs (pre-release version component in terms of semantic versioning). * currentVersion SemVer - The current application version. * **channel** String | "undefined" - Get the update channel. Not applicable for GitHub. Doesn't return `channel` from the update configuration, only if was previously set. @@ -1051,7 +1063,7 @@ Asks the server whether there is an update. #### `appUpdater.downloadUpdate(cancellationToken)` ⇒ Promise<Array<String>> Start downloading update manually. You can use this method if `autoDownload` option is set to `false`. -**Returns**: Promise<Array<String>> - Paths to downloaded files. +**Returns**: Promise<Array<String>> - Paths to downloaded files. - cancellationToken CancellationToken @@ -1081,7 +1093,7 @@ This is different from the normal quit event sequence. ### MacUpdater ⇐ [AppUpdater](#AppUpdater) **Kind**: class of [electron-updater](#module_electron-updater)
-**Extends**: [AppUpdater](#AppUpdater) +**Extends**: [AppUpdater](#AppUpdater) * [.MacUpdater](#MacUpdater) ⇐ [AppUpdater](#AppUpdater) * [`.quitAndInstall()`](#module_electron-updater.MacUpdater+quitAndInstall) @@ -1095,7 +1107,7 @@ This is different from the normal quit event sequence. #### `macUpdater.quitAndInstall()` -**Overrides**: [quitAndInstall](#module_electron-updater.AppUpdater+quitAndInstall) +**Overrides**: [quitAndInstall](#module_electron-updater.AppUpdater+quitAndInstall) #### `macUpdater.addAuthHeader(token)` Shortcut for explicitly adding auth tokens to request headers @@ -1116,7 +1128,7 @@ Asks the server whether there is an update. #### `macUpdater.downloadUpdate(cancellationToken)` ⇒ Promise<Array<String>> Start downloading update manually. You can use this method if `autoDownload` option is set to `false`. -**Returns**: Promise<Array<String>> - Paths to downloaded files. +**Returns**: Promise<Array<String>> - Paths to downloaded files. - cancellationToken CancellationToken @@ -1134,7 +1146,7 @@ Configure update provider. If value is `string`, [GenericServerOptions](/configu ### NsisUpdater ⇐ module:electron-updater/out/BaseUpdater.BaseUpdater **Kind**: class of [electron-updater](#module_electron-updater)
-**Extends**: module:electron-updater/out/BaseUpdater.BaseUpdater +**Extends**: module:electron-updater/out/BaseUpdater.BaseUpdater ### Provider **Kind**: class of [electron-updater](#module_electron-updater)