GITBOOK-159: Improve auto update docs

advanced/auto-update.md

@@ -1,21 +1,31 @@
+---
+description: Set up automatic updates for your Electron application
+---
+
 # Auto Update
 
-Setting up Auto Updates in your app with Electron Forge is mostly the same process [as described in the Electron docs](https://electronjs.org/docs/tutorial/updates).  Forge enhances your workflow by publishing your app to the right place for you.  There are two main ways you can do auto updates.
+Setting up Auto Updates in your app with Electron Forge is mostly the same process [as described in the Electron docs](https://electronjs.org/docs/tutorial/updates).  Forge enhances your workflow by publishing your app to the right place for you. There are three main ways you can do auto updates.
+
+## Open source apps: update.electronjs.org
+
+Open source apps hosted on GitHub can use a free auto update service from the Electron team, [update.electronjs.org](auto-update.md#update.electronjs.org). To use this module with Forge, set up the [GitHub Publisher](../config/publishers/github.md) and add the [`update-electron-app`](https://github.com/electron/update-electron-app) module to your app.
 
-## Open Source Apps - update.electronjs.org
+This setup is going to be around 2 lines of code and a few lines of configuration. It is by far the easiest way to set up auto updates if you're an open source app.
 
-Open Source apps hosted on [github.com](https://github.com) can use a free auto update service from the Electron team, `update.electronjs.org`. To use this with Forge, set up the [GitHub](../config/publishers/github.md) publisher and add the [`update-electron-app`](https://github.com/electron/update-electron-app) module to your app.
+## Hosting updates on static storage providers
 
-This setup is going to be around 2 lines of code and a few lines of configuration, by far the easiest way to set up auto updates if you're an open source app.
+If you are using any of Forge's built-in Publishers that upload your artifacts to static storage, they each have a documentation section on how to configure your app to auto update using those uploaded artifacts. Check out each of the options:
 
-## Host your own update server
+* [Amazon S3](../config/publishers/s3.md#auto-updating-from-s3)
+* Google Cloud Storage _(Coming Soon)_
 
-If you're not open source or you want slightly more control over your update service you can host your own update server such as [`nucleus`](https://github.com/atlassian/nucleus) or [`nuts`](https://github.com/GitbookIO/nuts).  See the full list of known Electron update servers in the [Electron's Updating Applications docs](https://electronjs.org/docs/tutorial/updates#deploying-an-update-server).
+## Hosting your own update server
+
+If you're not open source or you want slightly more control over your update service (like percentage based rollouts, or more release channels) you can host your own update server such as [`nucleus`](https://github.com/atlassian/nucleus) or [`nuts`](https://github.com/GitbookIO/nuts).  See the full list of known Electron update servers in the [Electron's Updating Applications docs](https://electronjs.org/docs/tutorial/updates#deploying-an-update-server).
 
 Each update server will have their own configuration for your actual app, but publishing should be done from Forge for most of them:
 
 * `nucleus` - Use the [Nucleus](../config/publishers/nucleus.md) publish target
 * `nuts` - Use the [GitHub](../config/publishers/github.md) publish target
 * `electron-release-server` - Use the [Electron Release Server](../config/publishers/electron-release-server.md) publish target
 * `hazel` - Use the [GitHub](../config/publishers/github.md) publish target
-

config/makers/zip.md

@@ -6,13 +6,10 @@ description: Create a ZIP file for your Electron app using Electron Forge.
 
 The Zip target builds basic `.zip` files containing your packaged application.There are no platform specific dependencies for using this maker and it will run on any platform.
 
-There are no configuration options for this target.
-
 ### Usage
 
 ```javascript
 {
   name: '@electron-forge/maker-zip'
 }
 ```
-

config/publishers/github.md

@@ -2,7 +2,7 @@
 
 The GitHub target publishes all your artifacts to GitHub releases, this allows your users to download the files straight from your repository or if your repository is open source you can use [update.electronjs.org](https://github.com/electron/update.electronjs.org) and get a free hosted update service.
 
-Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/_electron_forge_publisher_github.PublisherGitHubConfig.html)
+Configuration options are documented in [`PublisherGitHubConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_publisher\_github.PublisherGitHubConfig.html)
 
 {% hint style="info" %}
 You can use this target to publish to GitHub Enterprise using the host configuration options of `octokitOptions`. Check out the configuration options linked above.
@@ -29,3 +29,16 @@ module.exports = {
 };
 ```
 {% endcode %}
+
+### Auto updating from GitHub
+
+Updating from a GitHub release for a **public** repository is as simple as adding the [`update-electron-app`](https://github.com/electron/update-electron-app) module to your app's main process.
+
+{% code title="main.js" %}
+```javascript
+const { updateElectronApp } = require('update-electron-app');
+updateElectronApp(); // additional configuration options available
+```
+{% endcode %}
+
+If your GitHub release is in a private repository, you should check our [Auto Update](../../advanced/auto-update.md) guide for alternative solutions.

config/publishers/s3.md

@@ -27,16 +27,18 @@ module.exports = {
       }
     }
   ]
-};
+}
 ```
 {% endcode %}
 
 ### Key management
 
-By default, the S3 publisher will upload its objects to the`PREFIX/NAME` key, where:
+By default, the S3 publisher will upload its objects to the `{prefix}/{platform}/{arch}/{name}` key, where:
 
-* `PREFIX` is the value of the `config.folder` option (defaults to your package.json version).
-* `NAME` is the file name of the artifact you are publishing.
+* `{prefix}` is the value of the `config.folder` option (defaults to the `"name"` field in your package.json).
+* `{platform}` is the target platform for the artifact you are publishing.
+* `{arch}` is the target architecture for the artifact you are publishing.
+* `{name}` is the file name of the artifact you are publishing.
 
 {% hint style="warning" %}
 If you run the Publish command multiple times on the same platform for the same version (e.g. simultaneously publishing `ia32` and `x64` Windows artifacts), your uploads can get overwritten in the S3 bucket.
@@ -58,3 +60,60 @@ To avoid this problem, you can use the `keyResolver` option to generate the S3 k
 ```
 {% endcode %}
 {% endhint %}
+
+### Auto updating from S3
+
+You can configure Electron's built-in [`autoUpdater`](https://www.electronjs.org/docs/latest/api/auto-updater) module to use the artifacts published by the S3 publisher. This is a two-step process:
+
+First, you must configure `@electron-forge/publisher-s3` to publish your files into an auto-updater compatible layout and use `@electron-forge/maker-zip` + `@electron-forge/maker-squirrel` to build your application.
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  // ...
+  makers: [
+    {
+      name: '@electron-forge/maker-zip',
+      config: (arch) => ({
+        // Note that we must provide this S3 URL here
+        // in order to support smooth version transitions
+        // especially when using a CDN to front your updates
+        macUpdateManifestBaseUrl: 'https://my-bucket.s3.amazonaws.com/my-app-updates/darwin/${arch}/RELEASES.json'
+      })
+    },
+    {
+      name: '@electron-forge/maker-squirrel',
+      config: (arch) => ({
+        // Note that we must provide this S3 URL here
+        // in order to generate delta updates
+        remoteReleases: `https://my-bucket.s3.amazonaws.com/my-app-updates/win32/${arch}`,
+      })
+    }
+  ],
+  publishers: [
+    {
+      name: '@electron-forge/publisher-s3',
+      config: {
+        bucket: 'my-bucket',
+        public: true,
+      }
+    }
+  ]
+}
+```
+{% endcode %}
+
+With Forge configured correctly, the second step is to configure the `autoUpdater` module inside your app's main process. The simplest form is shown below but you might want to hook additional events to show UI to your user or ask them if they want to update your app right now.
+
+{% code title="main.js" %}
+```javascript
+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}`,
+  }
+});
+```
+{% endcode %}