Documentation for Auto Update and Publishing Artifacts need clarification #1224

antonycourtney · 2017-02-08T20:26:32Z

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.

The text was updated successfully, but these errors were encountered:

develar · 2017-02-09T08:27:37Z

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 · 2017-02-09T10:17:07Z

@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 · 2017-02-09T17:39:52Z

@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 · 2017-02-09T17:40:27Z

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

develar · 2017-02-09T18:12:57Z

@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 · 2017-02-09T18:17:23Z

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

develar · 2017-02-09T18:19:37Z

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

develar · 2017-02-09T18:20:36Z

cc @27percent

develar · 2017-02-09T18:22:33Z

Related: #1208

kutu · 2017-02-09T18:43:40Z

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 · 2017-02-09T18:59:01Z

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 · 2017-02-09T18:59:30Z

another one good feature is releaseNotes, but no documentation too

#1174 (comment)

iffy · 2017-02-09T20:06:50Z

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

akashnimare · 2017-02-09T20:08:04Z

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

akashnimare · 2017-02-09T21:13:42Z

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 · 2017-02-10T04:57:16Z

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 · 2017-02-10T05:02:28Z

...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 · 2017-02-10T21:13:38Z

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?

joshdotblack · 2017-02-11T19:19:05Z

@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 · 2017-02-11T19:45:02Z

@27percent Please file issue about timeout.

joshdotblack · 2017-02-11T20:26:16Z

@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 · 2017-02-17T19:06:54Z

CLI flags:

added:

Excerpt from CLI Usage of build command:

so, should be clear now.

develar · 2017-02-21T21:48:15Z

edited: docs published as md documents.

develar · 2017-03-25T15:09:48Z

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 · 2017-04-02T18:01:08Z

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

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

akashnimare · 2017-04-02T18:22:30Z

@MarkusSvensson awesome. I'll try it out.

develar added deployment electron-updater question readme improvement labels Feb 9, 2017

develar added a commit that referenced this issue Feb 9, 2017

docs: mention http support, fix electron-updater npm description #1224

861da29

develar added a commit to develar/electron-builder that referenced this issue Feb 17, 2017

docs: clarify tool CLI flags electron-userland#1224

e531017

develar added a commit that referenced this issue Feb 18, 2017

docs: clarify setFeeedURL #1224

9359357

develar added a commit that referenced this issue Mar 25, 2017

docs: document signals #1224

be698a8

develar closed this as completed in 4c83b3f Mar 25, 2017

luclu mentioned this issue Jul 24, 2017

Improve auto-updater ethereum/mist#2267

Open

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for Auto Update and Publishing Artifacts need clarification #1224

Documentation for Auto Update and Publishing Artifacts need clarification #1224

antonycourtney commented Feb 8, 2017

develar commented Feb 9, 2017

akashnimare commented Feb 9, 2017

antonycourtney commented Feb 9, 2017

antonycourtney commented Feb 9, 2017

develar commented Feb 9, 2017 •

edited

Loading

develar commented Feb 9, 2017

develar commented Feb 9, 2017

develar commented Feb 9, 2017 •

edited

Loading

develar commented Feb 9, 2017

kutu commented Feb 9, 2017 •

edited

Loading

develar commented Feb 9, 2017

develar commented Feb 9, 2017

iffy commented Feb 9, 2017

akashnimare commented Feb 9, 2017

akashnimare commented Feb 9, 2017 •

edited

Loading

antonycourtney commented Feb 10, 2017

antonycourtney commented Feb 10, 2017

iffy commented Feb 10, 2017

joshdotblack commented Feb 11, 2017

develar commented Feb 11, 2017

joshdotblack commented Feb 11, 2017

develar commented Feb 17, 2017

develar commented Feb 21, 2017 •

edited

Loading

develar commented Mar 25, 2017

MarkusSvensson commented Apr 2, 2017

akashnimare commented Apr 2, 2017

Documentation for Auto Update and Publishing Artifacts need clarification #1224

Documentation for Auto Update and Publishing Artifacts need clarification #1224

Comments

antonycourtney commented Feb 8, 2017

Auto Update Page

Example Project

Configuring Alternative Provider in Quick Setup Guide

Publishing Artifacts Page

GH_TOKEN

CLI Flags

Worked Example

Contribution and Thanks

develar commented Feb 9, 2017

akashnimare commented Feb 9, 2017

GH Token

How to generate it:

antonycourtney commented Feb 9, 2017

antonycourtney commented Feb 9, 2017

develar commented Feb 9, 2017 • edited Loading

develar commented Feb 9, 2017

develar commented Feb 9, 2017

develar commented Feb 9, 2017 • edited Loading

develar commented Feb 9, 2017

kutu commented Feb 9, 2017 • edited Loading

develar commented Feb 9, 2017

develar commented Feb 9, 2017

iffy commented Feb 9, 2017

akashnimare commented Feb 9, 2017

akashnimare commented Feb 9, 2017 • edited Loading

antonycourtney commented Feb 10, 2017

antonycourtney commented Feb 10, 2017

iffy commented Feb 10, 2017

joshdotblack commented Feb 11, 2017

develar commented Feb 11, 2017

joshdotblack commented Feb 11, 2017

develar commented Feb 17, 2017

develar commented Feb 21, 2017 • edited Loading

develar commented Mar 25, 2017

MarkusSvensson commented Apr 2, 2017

akashnimare commented Apr 2, 2017

develar commented Feb 9, 2017 •

edited

Loading

develar commented Feb 9, 2017 •

edited

Loading

kutu commented Feb 9, 2017 •

edited

Loading

akashnimare commented Feb 9, 2017 •

edited

Loading

develar commented Feb 21, 2017 •

edited

Loading