Electron: build a Linux package from Windows using electron-builder and Docker

Ryan

4 years ago

Table of Contents

Introduction
Adding the Linux JSON keys
Host your own (docker) Build Service
Conclusion

If you've stumbled upon this post it most likely means that you're struggling for a way to build your Electron app in a Linux distributable format such as the following: AppImage, deb, rpm, snap, freebsd, and so on. This guide has been written to help you with such specific task and will hopefully allow you to get the task done in less than five minutes.

In the unlikely case you don't know what we're talking about and you want to get additional info about the open-source framework designed to build desktop GUI applications known as Electron, we strongly suggest you to read our Electron and Visual Studio tutorial & guide to Hello World app first , which also contains a viable introduction to what the Electron framework actually is and how it can be used to build multi-platform desktop apps.

Introduction

In this post we'll make use of the tool known as electron-builder, which in our opinion is currently the best available solution to package and build a ready for distribution Electron app for macOS, Windows and Linux.

DISCLAIMER: This website is not affiliated with electron-builder; this article represents the free opinion of the author and has not been commissioned or sponsored in any way.

Installing electron-builder is very easy, we just have to have NodeJS installed and run the following command:

> yarn add electron-builder --dev

For additional info about installing and/or configuring the tool, please refer to the electron-builder official documentation: in a nutshell, you'll have to create a package.json file and configure it to your needs, then run electron-builder from the command-line (optionally with command-line options, depending on your specific scenario) and get your Electron app built.

For the sake of simplicity, we'll take for granted that the reader already knows how to configure it to build a distributable Windows package with a package.json similar to the following one:

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "That's just a sample description",
  "repository": "https://github.com/MyApp/my-app",
  "homepage": "https://github.com/MyApp/my-app",
  "author": {
    "name": "MyApp Owner",
    "email": "myapp-owner@myemail.com"
  },
  "license": "MIT",
  "keywords": [
    "Electron",
    "my-app",
    "MyApp"
  ],
  "main": "src/main.js",
  "scripts": {
    "start": "electron .",
    "pack": "electron-builder --dir",
    "distW": "electron-builder --ia32 --x64 -w",
    "dist": "electron-builder"
  },
  "build": {
    "appId": "com.my.app",
    "productName": "My App",
    "win": {
      "target": "nsis"
    },
    "nsis": {
      "oneClick": false,
      "perMachine": false,
      "allowToChangeInstallationDirectory": true
    },
    "artifactName": "MyApp_${version}_Setup.${ext}",
    "forceCodeSigning": false
  },
  "dependencies": {
    "@lapo/extractcms": "^1.0.3",
    "adm-zip": "^0.4.13",
    "xmldom": "^0.1.27"
  },
  "devDependencies": {
    "electron": "^4.0.3",
    "electron-builder": "^22.8.1"
  }
}

{

"name": "my-app",

"version": "1.0.0",

"description": "That's just a sample description",

"repository": "https://github.com/MyApp/my-app",

"homepage": "https://github.com/MyApp/my-app",

"author": {

"name": "MyApp Owner",

"email": "myapp-owner@myemail.com"

"license": "MIT",

"keywords": [

"Electron",

"my-app",

"MyApp"

"main": "src/main.js",

"scripts": {

"start": "electron .",

"pack": "electron-builder --dir",

"distW": "electron-builder --ia32 --x64 -w",

"dist": "electron-builder"

"build": {

"appId": "com.my.app",

"productName": "My App",

"win": {

"target": "nsis"

"nsis": {

"oneClick": false,

"perMachine": false,

"allowToChangeInstallationDirectory": true

"artifactName": "MyApp_${version}_Setup.${ext}",

"forceCodeSigning": false

"dependencies": {

"@lapo/extractcms": "^1.0.3",

"adm-zip": "^0.4.13",

"xmldom": "^0.1.27"

"devDependencies": {

"electron": "^4.0.3",

"electron-builder": "^22.8.1"

}

As we can see, the package.json contains the required JSON keys to build the distributable package for Windows (win and nsis), but there are no references for Linux yet. Let's start from here.

Adding the Linux JSON keys

Here are the required JSON keys to build a basic Linux distributable package (in deb format, thus compatible with Debian, Ubuntu and the likes) for our Electron App:

"linux": {
  "target": "deb"
},
"deb": {}

"linux": {

"target": "deb"

"deb": {}

These keys should be placed at the same level of the already-existing "win" and "nsis" keys, ideally immediately below them. Once you do that, you're ready to try and build your Electron App for Linux using the built-in multi-platrform build feature provided by electron-builder, which relies on a free public Electron Build Service that is internally called by the compiler and ideally performs the building task remotely (think of them as some free remote web services). That's great, right? As a matter of fact, it is...

...or maybe we should say it used to be, since such incredible feature is unfortunately broken since months, to the point that it seems unlikely to be fixed. Here's a collection of GitHub issues and StackOverflow threads that have been opened from users that are trying to deal with such issue:

... and so on.

Host your own (docker) Build Service

Until the complimentary Electron Build Service will become available again, the best workaround we can pull off is to try and host our own Build Service: luckily enough there's a great Docker image (electronuserland/builder) that can be used to achieve such result in few minutes. Here are the required steps:

Install Docker from the Get-Docker official website.
Download the electronuserland/builder image using the following command-prompt console command:

> docker pull electronuserland/builder

Navigate to your Electron project's root folder ( for example, C:\MyApp )
Run the electronuserland/builder container using the following command from the command line:

> docker run -rm -ti -v C:\MyApp\:/project -w /project electronuserland/builder

IMPORTANT: the above command-line is ok for most typical scenarios, but might not work for complex Electron projects with a lot of dependencies: in case it doesn't work for you, refer to this CLI example and the official docker run reference guide to see if you need to link and/or reference additional packages, environment variables and so on.

The above command will launch the Docker container with your Electron App's root folder mounted inside the /project/ virtual path. Once you get the docker's container prompt - a Linux terminal by all means - type the following commands to get inside that folder, upgrade your Electron project's Yarn packages, globally install the electron-builder package and, last but not least, build the Linux redistributable package.

> cd /project

> yarn upgrade

> yarn global add electron-builder

> electron-builder

If everything went smooth, you should be able to locate your MyApp.deb file inside the Electron project's /dist/ folder.

Conclusion

That's it, at least for now: I hope that this post will help those who're looking for a way to build their Electron App for Linux from their Windows environment in a quick and effective way.

Print Friendly & PDF Download