Electron-builder: Documentation for Auto Update and Publishing Artifacts need clarification

[antonycourtney]

• Version: 10.6.1

• Target: Mac OS/X

Numerous aspects of the documentation on auto update and publishing artifacts omit many essential details. I'm sure it's the case that many of these details are "implicit mental context" that is obvious to the developers of electron-builder and those who have already used it extensively, but they make it difficult or impossible for a newcomer to understand how the process works and what's needed.

Auto Update Page

Example Project

To begin with: The Auto Update Page has a link to an Example Project.

I've cloned this example project and read the source for AppUpdater.ts and looked through all of the config files. Where is the configuration that determines the location where the app updater will fetch new releases? Nothing seemed obvious. Is it perhaps just pulling release artifacts from github directly as a default, based on the repository of package.json? It would be really helpful if there was a sentence or two on the Auto Update page clarifying this. If it's configured explicitly and I've overlooked it, would be helpful to have a link to the config file; if it's all done by defaults, it would be helpful to clarify that and mention where to place config settings to override those defaults.

Configuring Alternative Provider in Quick Setup Guide

Step 4 of the Quick Setup Guide mentions that one should not explicitly call setFeedURL, and provides a short snippet showing how one can specify an explicit "provider":

{
  provider: "bintray",
  owner: "actperepo",
  package: "no-versions"
}

but where, exactly, does one place this configuration snippet? In what configuration file, and under what key? It's not clear.

Publishing Artifacts Page

This page mentions that Travis and AppVeyor are both supported. In the text that follows, are the configuration details and "CLI flags" referring to configuration and flags for these CI tools, or for electron-builder itself?

GH_TOKEN

This sentence:

electron-builder allows you to just add GH_TOKEN environment variable and that's all.

could use some clarification. What is GH_TOKEN, what is its format, and what is the effect of setting this? In a typical build setup (or the example project), where would it be set?

CLI Flags

Are these flags command line flags that should be passed to electron-builder (rather than to some other utility related to the build process or use of CI server)? I assume so, but it would be helpful to clarify.

Are these CLI Flags only relevant when using a CI server, or are they also relevant when building and publishing a release manually? I suspect they are useful in both cases, but it would be good to clarify.

Worked Example

It would be tremendously helpful to have a worked example of the exact sequence of shell commands to be run after making a change to the source code to build and publish a new release.

Contribution and Thanks

I know I'm asking a lot with the above.

I am happy to contribute text or editing to help clarify any of the above if someone will answer the above questions and walk me through the process. I will also certainly make a donation to this great project to increase priority of this issue. Thanks for the great work developing electron-builder and thanks in advance for any help answering these questions.

[develar]

Thanks for donation and clear explanation.

Let's solve step by step.

Configuring Alternative Provider in Quick Setup Guide

What is not clear in the "electron-builder automatically creates app-update.yml file for you on build in the resources"? In the "But if need, you can — for example"?

Why it is not clear that electron-builder automatically creates for you all required info? Or it is not clear that this configuration is taken from step 2 "Configure publish"?

[akashnimare]

@antonycourtney I have successfully implemented auto-updates using electron-updater. You can check it out here -
Auto update function -
https://github.com/zulip/zulip-electron/blob/master/app/main/autoupdater.js
Package.json -
https://github.com/zulip/zulip-electron/blob/master/package.json

Another example -
https://github.com/iffy/electron-updater-example

GH Token

https://help.github.com/articles/creating-an-access-token-for-command-line-use/

How to generate it:

You can generate a GitHub access token by going to https://github.com/settings/tokens/new. The access token should have the repo scope/permission. Once you have the token, assign it to an environment variable (on macOS/Linux). Type this in your terminal or add it to your ~/.bashrc

    export GH_TOKEN="<YOUR_TOKEN_HERE>"

Hope it helps 😄

[antonycourtney]

@develar - Thanks for your help!

What is not clear in the "electron-builder automatically creates app-update.yml file for you on build in the resources"? In the "But if need, you can — for example"?

To begin with it's not clear exactly what file to modify to add the snippet shown in the example.

Are you suggesting that developers can modify the automatically generated app-update.yml file that is automatically created in the resources directory? If so, that's OK, but I think it's worth stating explicitly. And then this raises the additional question: What will happen to these modifications the next time the build process is run? Will the file be overwritten? Will the generated file simply be updated, but leaving any developer modifications in place? It's not clear.
An alternative possibility is that perhaps the snippet provided is somehow placed in a config files used in the publish step, to avoid the thorny issues with manual modifications to auto-generated config files...again, impossible to know if that's what's being proposed since this doc doesn't specify what file is to be modified.

Why it is not clear that electron-builder automatically creates for you all required info? Or it is not clear that this configuration is taken from step 2 "Configure publish"?

It would be helpful (to me at least) to understand a little about what information electron-builder derives automatically from the publish step. At the very minimum, while the docs make it clear that one does not need to explicitly call setFeedURL to specify the URL that will be used to obtain updates, what URL will actually be used and how is this derived from the publish configuration? It's not obvious to me how this is derived from the configuration information used for the publish step.

[antonycourtney]

@akashnimare Many thanks for this, and for the details on GH_TOKEN - will take a look!

[develar]

@antonycourtney Got it, thanks. Provided snipped should passed to setFeedURL. I will fix docs according to your excellent explanation.

@akashnimare I will grab your text about Token ;) and will update docs.

[develar]

CLI flags — to electron-builder. Applicable locally as well. I will update docs.

[develar]

Worked example — @iffy? https://github.com/iffy/electron-updater-example

[develar]

cc @27percent

[develar]

Related: #1208

[kutu]

i agree with topic starter

package says "nsis auto updater", does it mean it only works with nsis target release, need clarification if it works with squirrel too

wiki says, it will generate app-update.yml and latest.yml, found first but not second file (generic provider), maybe because i use squirrel target

Currently, generic (any HTTPS web server)

does that mean http will not work?

in onshape example app, you use autoUpdater.signals.updateDownloaded to handle event, but autoUpdater.on('checking-for-update') still works, what should we use

so far, this package bring 2 unnecessary files and confusion, whilst original just works, the only reason i want to use electron-updater is "download-progress" event, but i keep using original one, cause still can't figure out electron-updater

another one good feature is releaseNotes, but no documentation too

[develar]

package says "nsis auto updater"

Fixed to Cross platform updater for electron applications.

need clarification if it works with squirrel too

Squirrel.Windows is deprecated. For Squirrel.Windows you can use built-in updater.

maybe because i use squirrel target

Yes.

does that mean http will not work?

HTTP supported. Fixed to HTTP(S)

what should we use

To be documented.

[develar]

another one good feature is releaseNotes, but no documentation too

https://github.com/electron-userland/electron-builder/issues/1174#issuecomment-276881877

[iffy]

@develar it almost works -- I just need to try it with code signing.

[akashnimare]

@iffy FYI it works perfectly (tried it with code sign) 🚀

[akashnimare]

I'm still not able to figure out how to get version, releaseName and releaseNotes. Despite of adding releaseName and releaseNotes in my latest-mac.json, info.releaseName and info.releaseNotes are undefined 😭

[antonycourtney]

Hi @iffy -- Thanks so much for this example. The instructions are super clear, and it almost works for me. I managed to create and publish a release, install the publish release, bump the version number and republish.

However, when I upgrade the version number and publish a new release, and then run the previous version, the application window looks like:

Digging in to the log file, I see:

[2017-02-09 19:27:18:0371] [info] App starting...
[2017-02-09 19:27:19:0484] [info] Checking for update
[2017-02-09 19:27:19:0484] [info] Checking for update...
[2017-02-09 19:27:20:0340] [error] Error: Error: Unable to find latest version on github, please ensure a production release exists: SyntaxError: Unexpected end of JSON input
SyntaxError: Unexpected end of JSON input
    at JSON.parse (<anonymous>)
    at IncomingMessage.response.on (/Applications/electron-updater-example.app/Contents/Resources/app.asar/node_modules/electron-updater/node_modules/electron-builder-http/src/httpExecutor.ts:129:56)
    at emitNone (events.js:86:13)
    at IncomingMessage.emit (events.js:185:7)
    at endReadableNT (_stream_readable.js:974:12)
    at _combinedTickCallback (internal/process/next_tick.js:74:11)
    at process._tickCallback (internal/process/next_tick.js:98:9)
...

Unfortunately, it doesn't look like there's an easy way to see what URL is being used to check for updates.

Which gets back to my previous question for @develar -- how is URL used to check for updates constructed? It's great that it is automatically generated, but when the update process isn't working, it's really necessary to know what the URL is and how's it's derived.

Thanks for all the help -- almost there!

[antonycourtney]

...actually I see now what the problem was, the clue being production in:

[2017-02-09 19:27:20:0340] [error] Error: Error: Unable to find latest version on github, please ensure a production release exists: SyntaxError: Unexpected end of JSON input

I edited the release to uncheck the pre-release checkbox, and all worked perfectly.

Thanks. I highly encourage changing the wiki pages to just link to this example, it makes the whole process quite clear.

[iffy]

I think @antonycourtney is right: when there's an error trying to find a release on GitHub, it would be really helpful for the logs to say what URL was requested. I'm seeing the following:

[2017-02-10 14:09:20:0311] [error] Error: Error: Unable to find latest version on github, please ensure a production release exists: Error: net::ERR_NOT_IMPLEMENTED
    at Error (native)
From previous event:
    at ElectronHttpExecutor.doApiRequest (/Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/src/electronHttpExecutor.ts:44:5)
    at ElectronHttpExecutor.request (/Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-builder-http/src/httpExecutor.ts:73:17)
    at request (/Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-builder-http/src/httpExecutor.ts:207:38)
    at /Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/src/GitHubProvider.ts:19:19
    at next (<anonymous>)
From previous event:
    at GitHubProvider.getLatestVersion (/Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/src/GitHubProvider.ts:47:4)
    at /Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/src/AppUpdater.ts:152:38
From previous event:
    at MacUpdater.doCheckForUpdates (/Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/out/AppUpdater.js:219:11)
    at /Users/matt/m/lhtml/dist/mac/LHTML.app/Contents/Resources/app.asar/node_modules/electron-updater/src/AppUpdater.ts:137:25
    at next (<anonymous>)
    at runCallback (timers.js:574:20)
    at tryOnImmediate (timers.js:554:5)
    at processImmediate [as _immediateCallback] (timers.js:533:5)

Should I file a separate issue?

[consolenaut]

@iffy I can's speak for you, but using electron 1.4.15, electron-builder 12.3.1 & electron-updater 1.4.2 on MacOS I'm getting log files containing the github request URL as follows:

[2017-02-10 19:00:53:0293] [info] App starting...
[2017-02-10 19:00:54:0328] [info] Checking for update
[2017-02-10 19:00:54:0328] [info] Checking for update...
[2017-02-10 19:00:57:0580] [info] Found version 0.3.4 (url: https://github.com/27percent/electron-updater-example/releases/download/v0.3.4/electron-updater-example-0.3.4-mac.zip)
[2017-02-10 19:00:57:0580] [info] Update available.
[2017-02-10 19:00:57:0581] [info] info undefined
[2017-02-10 19:00:57:0582] [info] Downloading update from https://github.com/27percent/electron-updater-example/releases/download/v0.3.4/electron-updater-example-0.3.4-mac.zip
[2017-02-11 18:58:05:0595] [info] App starting...
[2017-02-11 18:58:06:0625] [info] Checking for update
[2017-02-11 18:58:06:0626] [info] Checking for update...
[2017-02-11 18:58:07:0794] [info] Found version 0.3.5 (url: https://github.com/27percent/electron-updater-example/releases/download/v0.3.5/electron-updater-example-0.3.5-mac.zip)
[2017-02-11 18:58:07:0794] [info] Update available.
[2017-02-11 18:58:07:0795] [info] info undefined
[2017-02-11 18:58:07:0796] [info] Downloading update from https://github.com/27percent/electron-updater-example/releases/download/v0.3.5/electron-updater-example-0.3.5-mac.zip
[2017-02-11 19:00:24:0130] [warn] Error: The request timed out.
    at Error (native)
[2017-02-11 19:00:24:0132] [error] Error: Error: The request timed out.
    at Error (native)
[2017-02-11 19:00:24:0132] [info] Error in auto-updater.
[2017-02-11 19:00:24:0133] [info] err undefined

I am having a bit of an issue with request timeout though, given the update isn't a small file, it takes a little while to download and electron updater doesn't seem to be waiting for the download to complete - on faster connections it seems to be fine, I'm guessing there's maybe a 1-2 minute timeout and if the download isn't complete in this time, the update stops and emits an error - is that roughly correct?

[develar]

@27percent Please file issue about timeout.

[consolenaut]

@develar Will do, apologies, I should've stayed on-topic. Thanks for mentioning me so I'd get a notification by the way, this thread has been really helpful, I'm a lot closer to completing my project because of it

[develar]

CLI flags:

added:

Excerpt from CLI Usage of build command:

so, should be clear now.

[develar]

edited: docs published as md documents.

[develar]

in onshape example app, you use autoUpdater.signals.updateDownloaded to handle event, but autoUpdater.on('checking-for-update') still works, what should we use

https://github.com/electron-userland/electron-builder/wiki/Auto-Update#AppUpdater-signals

[MarkusSvensson]

@akashnimare With below code I could get hold of releaseNotes etc

autoUpdater.on('update-downloaded', (...args) => {
  message += 'Release notes: ' + args[0].releaseNotes;
  ...
}

[akashnimare]

@MarkusSvensson awesome. I'll try it out.