Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: update tutorials for Forge 6 #36322

Merged
merged 1 commit into from Nov 14, 2022
Merged

docs: update tutorials for Forge 6 #36322

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
49 changes: 12 additions & 37 deletions docs/tutorial/code-signing.md
View file
Open in desktop
Expand Up @@ -52,15 +52,17 @@ ways to get your application signed and notarized.
If you're using Electron's favorite build tool, getting your application signed
and notarized requires a few additions to your configuration. [Forge](https://electronforge.io) is a
collection of the official Electron tools, using [`electron-packager`],
[`electron-osx-sign`], and [`electron-notarize`] under the hood.
[`@electron/osx-sign`], and [`@electron/notarize`] under the hood.

Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos).
Detailed instructions on how to configure your application can be found in the
[Signing macOS Apps](https://www.electronforge.io/guides/code-signing/code-signing-macos) guide in
the Electron Forge docs.

### Using Electron Packager

If you're not using an integrated build pipeline like Forge, you
are likely using [`electron-packager`], which includes [`electron-osx-sign`] and
[`electron-notarize`].
are likely using [`electron-packager`], which includes [`@electron/osx-sign`] and
[`@electron/notarize`].

If you're using Packager's API, you can pass [in configuration that both signs
and notarizes your application](https://electron.github.io/electron-packager/main/interfaces/electronpackager.options.html).
Expand All @@ -70,40 +72,14 @@ const packager = require('electron-packager')

packager({
dir: '/path/to/my/app',
osxSign: {
identity: 'Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)',
'hardened-runtime': true,
entitlements: 'entitlements.plist',
'entitlements-inherit': 'entitlements.plist',
'signature-flags': 'library'
},
osxSign: {},
osxNotarize: {
appleId: 'felix@felix.fun',
appleIdPassword: 'my-apple-id-password'
}
})
```

The `entitlements.plist` file referenced here needs the following macOS-specific entitlements
to assure the Apple security mechanisms that your app is doing these things
without meaning any harm:

```xml title="entitlements.plist"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.debugger</key>
<true/>
</dict>
</plist>
```

Up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required
as well. However, it should not be used anymore if it can be avoided.

### Signing Mac App Store applications

See the [Mac App Store Guide].
Expand Down Expand Up @@ -213,15 +189,14 @@ can find [its documentation here](https://www.electron.build/code-signing).
See the [Windows Store Guide].

[apple developer program]: https://developer.apple.com/programs/
[`electron-builder`]: https://github.com/electron-userland/electron-builder
[`electron-forge`]: https://github.com/electron-userland/electron-forge
[`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign
[`electron-forge`]: https://github.com/electron/forge
[`@electron/osx-sign`]: https://github.com/electron/osx-sign
[`electron-packager`]: https://github.com/electron/electron-packager
[`electron-notarize`]: https://github.com/electron/electron-notarize
[`@electron/notarize`]: https://github.com/electron/notarize
[`electron-winstaller`]: https://github.com/electron/windows-installer
[`electron-wix-msi`]: https://github.com/felixrieseberg/electron-wix-msi
[`electron-wix-msi`]: https://github.com/electron-userland/electron-wix-msi
[xcode]: https://developer.apple.com/xcode
[signing certificates]: https://github.com/electron/electron-osx-sign/wiki/1.-Getting-Started#certificates
[signing certificates]: https://developer.apple.com/support/certificates/
[mac app store guide]: ./mac-app-store-submission-guide.md
[windows store guide]: ./windows-store-guide.md
[maker-squirrel]: https://www.electronforge.io/config/makers/squirrel.windows
Expand Down
18 changes: 9 additions & 9 deletions docs/tutorial/mac-app-store-submission-guide.md
View file
Open in desktop
Expand Up @@ -11,7 +11,7 @@ This guide provides information on:
To sign Electron apps, the following tools must be installed first:

* Xcode 11 or above.
* The [electron-osx-sign][electron-osx-sign] npm module.
* The [@electron/osx-sign] npm module.

You also have to register an Apple Developer account and join the
[Apple Developer Program][developer-program].
Expand Down Expand Up @@ -103,7 +103,7 @@ Apps submitted to the Mac App Store must run under Apple's
the App Sandbox. The standard darwin build of Electron will fail to launch
when run under App Sandbox.

When signing the app with `electron-osx-sign`, it will automatically add the
When signing the app with `@electron/osx-sign`, it will automatically add the
necessary entitlements to your app's entitlements, but if you are using custom
entitlements, you must ensure App Sandbox capacity is added:

Expand All @@ -120,7 +120,7 @@ entitlements, you must ensure App Sandbox capacity is added:

#### Extra steps without `electron-osx-sign`

If you are signing your app without using `electron-osx-sign`, you must ensure
If you are signing your app without using `@electron/osx-sign`, you must ensure
the app bundle's entitlements have at least following keys:

```xml
Expand Down Expand Up @@ -170,22 +170,22 @@ your Apple Developer account's Team ID as its value:
</plist>
```

When using `electron-osx-sign` the `ElectronTeamID` key will be added
When using `@electron/osx-sign` the `ElectronTeamID` key will be added
automatically by extracting the Team ID from the certificate's name. You may
need to manually add this key if `electron-osx-sign` could not find the correct
need to manually add this key if `@electron/osx-sign` could not find the correct
Team ID.

### Sign apps for development

To sign an app that can run on your development machine, you must sign it with
the "Apple Development" certificate and pass the provisioning profile to
`electron-osx-sign`.
`@electron/osx-sign`.

```bash
electron-osx-sign YourApp.app --identity='Apple Development' --provisioning-profile=/path/to/yourapp.provisionprofile
```

If you are signing without `electron-osx-sign`, you must place the provisioning
If you are signing without `@electron/osx-sign`, you must place the provisioning
profile to `YourApp.app/Contents/embedded.provisionprofile`.

The signed app can only run on the machines that registered by the provisioning
Expand Down Expand Up @@ -213,7 +213,7 @@ use App Sandbox.
electron-osx-sign YourApp.app --identity='Developer ID Application' --no-gatekeeper-assess
```

By passing `--no-gatekeeper-assess`, the `electron-osx-sign` will skip the macOS
By passing `--no-gatekeeper-assess`, `@electron/osx-sign` will skip the macOS
GateKeeper check as your app usually has not been notarized yet by this step.

<!-- TODO(zcbenz): Add a chapter about App Notarization -->
Expand Down Expand Up @@ -341,7 +341,7 @@ Electron uses following cryptographic algorithms:
* RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004)

[developer-program]: https://developer.apple.com/support/compare-memberships/
[electron-osx-sign]: https://github.com/electron/electron-osx-sign
[@electron/osx-sign]: https://github.com/electron/electron-osx-sign
[app-sandboxing]: https://developer.apple.com/app-sandboxing/
[app-notarization]: https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution
[submitting-your-app]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/AppDistributionGuide/SubmittingYourApp/SubmittingYourApp.html
Expand Down
9 changes: 9 additions & 0 deletions docs/tutorial/tutorial-1-prerequisites.md
View file
Open in desktop
Expand Up @@ -26,6 +26,15 @@ work on Windows, macOS, and Linux with a single JavaScript codebase.
This tutorial will guide you through the process of developing a desktop
application with Electron and distributing it to end users.

## Goals

This tutorial starts by guiding you through the process of piecing together
a minimal Electron application from scratch, then teaches you how to
package and distribute it to users using Electron Forge.

If you prefer to get a project started with a single-command boilerplate, we recommend you start
with Electron Forge's [`create-electron-app`](https://www.electronforge.io/) command.

## Assumptions

Electron is a native wrapper layer for web apps and is run in a Node.js environment.
Expand Down
92 changes: 39 additions & 53 deletions docs/tutorial/tutorial-5-packaging.md
View file
Open in desktop
Expand Up @@ -70,10 +70,9 @@ the [Electron Forge CLI documentation].
:::

You should also notice that your package.json now has a few more packages installed
under your `devDependencies`, and contains an added `config.forge` field with an array
of makers configured. **Makers** are Forge plugins that create distributables from
your source code. You should see multiple makers in the pre-populated configuration,
one for each target platform.
under `devDependencies`, and a new `forge.config.js` file that exports a configuration
object. You should see multiple makers (packages that generate distributable app bundles) in the
pre-populated configuration, one for each target platform.

### Creating a distributable

Expand Down Expand Up @@ -111,13 +110,14 @@ Electron Forge can be configured to create distributables in different OS-specif

:::

:::tip Creating and Adding Application Icons
:::tip Creating and adding application icons

Setting custom application icons requires a few additions to your config. Check out [Forge's icon tutorial] for more information.
Setting custom application icons requires a few additions to your config.
Check out [Forge's icon tutorial] for more information.

:::

:::note Packaging without Electron Forge
:::info Packaging without Electron Forge

If you want to manually package your code, or if you're just interested understanding the
mechanics behind packaging an Electron app, check out the full [Application Packaging]
Expand All @@ -136,64 +136,51 @@ Code signing is a security technology that you use to certify that a desktop app
created by a known source. Windows and macOS have their own OS-specific code signing
systems that will make it difficult for users to download or launch unsigned applications.

If you already have code signing certificates for Windows and macOS, you can set your
credentials in your Forge configuration. Otherwise, please refer to the full
[Code Signing] documentation to learn how to purchase a certificate and for more information
on the desktop app code signing process.

On macOS, code signing is done at the app packaging level. On Windows, distributable installers
are signed instead.
are signed instead. If you already have code signing certificates for Windows and macOS, you can set
your credentials in your Forge configuration.

:::info

For more information on code signing, check out the
[Signing macOS Apps](https://www.electronforge.io/guides/code-signing) guide in the Forge docs.

:::

<Tabs>
<TabItem value="macos" label="macOS" default>

```json title='package.json' {6-18}
{
//...
"config": {
"forge": {
//...
"packagerConfig": {
"osxSign": {
"identity": "Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)",
"hardened-runtime": true,
"entitlements": "entitlements.plist",
"entitlements-inherit": "entitlements.plist",
"signature-flags": "library"
},
"osxNotarize": {
"appleId": "felix@felix.fun",
"appleIdPassword": "this-is-a-secret"
}
}
//...
```js title='forge.config.js'
module.exports = {
packagerConfig: {
osxSign: {},
//...
osxNotarize: {
tool: 'notarytool',
appleId: process.env.APPLE_ID,
appleIdPassword: process.env.APPLE_PASSWORD,
teamId: process.env.APPLE_TEAM_ID,
}
//...
}
//...
}
```

</TabItem>
<TabItem value="windows" label="Windows">

```json title='package.json' {6-14}
{
```js title='forge.config.js'
module.exports = {
//...
"config": {
"forge": {
//...
"makers": [
{
"name": "@electron-forge/maker-squirrel",
"config": {
"certificateFile": "./cert.pfx",
"certificatePassword": "this-is-a-secret"
}
}
]
//...
}
}
makers: [
{
name: '@electron-forge/maker-squirrel',
config: {
certificateFile: './cert.pfx',
certificatePassword: process.env.CERTIFICATE_PASSWORD,
},
},
],
//...
}
```
Expand All @@ -214,13 +201,12 @@ information.

[`@electron/osx-sign`]: https://github.com/electron/osx-sign
[application packaging]: ./application-distribution.md
[code signing]: ./code-signing.md
[`electron-packager`]: https://github.com/electron/electron-packager
[`electron-winstaller`]: https://github.com/electron/windows-installer
[electron forge]: https://www.electronforge.io
[electron forge cli documentation]: https://www.electronforge.io/cli#commands
[makers]: https://www.electronforge.io/config/makers
[Forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons
[forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons

<!-- Tutorial links -->

Expand Down
36 changes: 15 additions & 21 deletions docs/tutorial/tutorial-6-publishing-updating.md
View file
Open in desktop
Expand Up @@ -78,27 +78,21 @@ Once you have it installed, you need to set it up in your Forge
configuration. A full list of options is documented in the Forge's
[`PublisherGitHubConfig`] API docs.

```json title='package.json' {6-16}
{
//...
"config": {
"forge": {
"publishers": [
{
"name": "@electron-forge/publisher-github",
"config": {
"repository": {
"owner": "github-user-name",
"name": "github-repo-name"
},
"prerelease": false,
"draft": true
}
}
]
}
}
//...
```js title='forge.config.js'
module.exports = {
publishers: [
{
name: '@electron-forge/publisher-github',
config: {
repository: {
owner: 'github-user-name',
name: 'github-repo-name',
},
prerelease: false,
draft: true,
},
},
],
}
```

Expand Down