jDeploy 5 Developer Guide

jDeploy 5 introduces a new desktop application that makes it easier than ever to deploy your jar is a native desktop application.

Quick Start

Installation

Download and install the jDeploy desktop application for your platform. macOS, Windows, and Linux are supported.

Main Menu

The jDeploy main menu, shown below, provides 3 main options:

Open Project - Use this if you have already set up your application with jDeploy.
Import Project - Use this if you have an jar file that you would like to deploy.
Create New Project - Use this if you would like to create a new project from scratch.

Import Project: Convert your existing jar file to a native application

If you already have a jar file (or a project that produces an executable jar file), you should use the "Import Project" option in the main menu to configure jDeploy to deploy your jar file as a native application.

Either enter the path to your project’s directory in the provided text field, or press "Select…" to select it from a file chooser dialog.

Tip	Generally, it is best to select the directory of your project, which is the one containing your `pom.xml` file, or your `build.gradle` file.

If you intend to use GitHub actions to automatically deploy your application in response to commit and tag events, then you can check the "Generate GitHub Workflow" checkbox. This will generate a basic workflow in the .github/workflows directory.

Once you have selected your project directory, press "Import"

Note	Creating a jdeploy project will generate a file named `package.json` in your project’s directory. This file will be used to store the configuration for deploying your application.

This should open the project editor dialog, as shown below:

This dialog allows you to configure your desktop application. You can configure such things as: . App icon . Installer splash screen . Java version . File and URL associations . Display name . Publish targets

See The Project Editor Dialog for more information about the fields and options available in the project editor.

jDeploy does its best to find your app’s main jar file. You should see the path (relative to project root) in the JAR File field. If this is incorrect, or empty, the first thing you’ll want to do is to correct this. Press the "Select…" button to select the correct jar file.

Tip	Make sure that you have built your project so that there is a jar file to find!

The name and title fields will also be populated with default values, based on the name of your Jar file. Inspect these and change as desired. The critical fields, for publishing your application, are the Name, Version, Title, and Author fields.

The Name field should be your globally unique project name. If you are publishing to npm, for example, this will be the name of your npm package.

The Title field is the human-readable title of your application. This is what will be displayed in the application menu, and in the installer.

Note

Importing a project will create a package.json file in your project’s directory. This file will be used to store the configuration for deploying your application. You’ll also notice a .jdeploy directory, which is used to store metadata used by the jDeploy desktop application. Additionally, if you selected the "Generate GitHub Workflow" option, you’ll see a .github/workflows directory with a workflow file named jdeploy.yml that will be used to deploy your application to GitHub releases.

Publishing your application

Currently (as of jDeploy 5.0.0), jDeploy supports publishing to the following platforms:

GitHub Releases
npm

To publish your application, you’ll need to configure the Publish Targets section of the project editor dialog. By default, you’ll find that npm is selected as a publish target. If you don’t want to publish to npm, you can uncheck this option.

Generating an npm token

For the purposes of this "Getting started" tutorial, we are going to publish to npm. To do this, you’ll need to have an npm account, and you’ll need to generate a token that you can use to authenticate with npm. You can generate a token by visiting the following URL:

https://www.npmjs.com/settings/your-username/tokens

Replace your-username with your npm username.

Click on the "Generate Token" button, to create a new token. You can either choose a granular access token or a class token. Either will work, as long as it has publish permissions.

Copy this token into a safe place. You’ll need it in the next step.

Publishing to npm

Now, back in the jDeploy project editor for your application, press the "Publish" button in the lower right of the dialog.

Important

Before publishing, you should save any changes you’ve made to the configuration by selecting "File" > "Save" from the menu, or simply pressing Ctrl+S (or Cmd+S on macOS).

You will be prompted to confirm that you want to publish your application, as shown below:

Click "Yes" to proceed.

Next, you’ll be asked to select the npm account you wish to use to publish your application. If you haven’t already configured an npm account, you can do so by pressing the "Add Account" button.

Since this is our first time using jDeploy, you’ll need to add an account.

The account name field name be any identifier you choose. It doesn’t need to match your npm username. It is just for you to identify the account.

The Token field is where you’ll paste the token that you generated in the previous step.

Note	The token will be stored in your system’s keychain, so you won’t need to enter it again in the future.

Press "Save", to return to the account selection dialog. Then press "Continue" to proceed with publishing your application.

Depending on your npm account settings, you might be prompted to enter a one-time password (OTP) to authenticate. If so, you’ll see a dialog like the one shown below:

If you have set up your npm account for 2-factor authentication, then you can simply enter the code from your authenticator app. If you haven’t set up 2-factor authentication, then you have two options:

Set up 2-factor authentication for your npm account.
Adjust your account settings to allow publishing without 2-factor authentication.

See the npm documentation for more information on how to set up 2-factor authentication for your npm account.

Once you have entered the OTP, or if you don’t need to enter one, the publishing process will continue.

If all goes well, you should see a dialog like the one shown below:

You can click on "View Download Page" to download your application. The URL for this download page will remain constant for all future releases of your application, so you can link to it from your website, or share it with your users.

Note	The download page is hosted on jdeploy.com, and provides downloads for your app’s installer, however, it doesn’t actually host your app. The installer that users download from this page will download your app from npm’s repository at install time.

Installing your application

To install your application, simply download the installer for your platform from the download page, and run it. The installer will guide you through the installation process.

E.g. On windows, it will download the installer as an exe file. You can run this directly from your browser’s downloads:

On macOS, it will download a .tar.gz file with an .app file inside. You can extract this file and run the .app file to install your application.

Tip	jDeploy also supports DMG file distribution for macOS, but this requires some configuration, as well as set up for code signing. This is not covered in this "Getting Started" tutorial.

Linux provides 3 different options for installation:

.deb package
.bin installer
Command-line installation snippet that you can run in your terminal.

Choose the option that is most appropriate for your system.

The vanilla installer UI is shown below. We’ll cover later, how you can customize this to match your app’s branding.

On Windows it provides options to add to the Start menu, as well as adding a desktop shortcut. On macOS it will provide an option to add to the Dock instead of the start menu.

Users can select the auto-update settings that they prefer. Recommended to leave it "On" so that the application will automatically download updates for your application when they are available.

Click the "Install" button to proceed with the installation.

This will prompt you with a confirmation dialog as shown below:

Click "Yes" to proceed with the installation.

Tip	By default this says that the application’s home page is at npmjs.com. If you published to GitHub releases, it would, instead, show the URL to your GitHub repository. Later we’ll learn how to change this to point to your own website.

Important

This confirmation step is important to prevent malware, and provide the user with a change to verify that the software is from a trusted source. The jDeploy installer is signed using the jDeploy’s code signing certificate, so it should be trusted by most systems so that you don’t need to jump through the hoops of code-signing yourself. So the installer is considered trusted, but the user must still confirm that they trust the software that the installer is installing.

Once you have confirmed, the installation will proceed.

If all goes well, you should see a dialog like the one shown below:

Click "Open <Your application name>" to launch your application.

Notice, that the application should also be available via the start menu.

Publishing to GitHub Releases

If you would like to publish your application to GitHub releases, instead of, or in addition to, npm, you can do so by configuring the Publish Settings tab of the project editor dialog.

Select the "Publish releases to GitHub" checkbox to enable this option. You should also provide the URL to the GitHub repository where you would like to publish your releases.

Important

This GitHub repository needs to be public so that the jDeploy installer is able to download updates from it. You may use a different repository than where your application sources are stored, if you want to keep your sources private. This repository need just be used to publish releases.

Generating a GitHub Personal Access Token

To publish to GitHub releases, you’ll need to generate a personal access token. See the GitHub documentation for details on creating your token. You can use a classic token or a fine-grained token, as long as it has permission to publish releases.

Publishing to GitHub

Once you have configured your GitHub repository and generated your personal access token, you can press the "Publish" button in the project editor dialog to publish your application.

In the project editor, click on the "Publish" button in the lower right of the dialog.

This will prompt you to confirm that you want to publish your application.

Click "Yes" to proceed.

Next, you’ll be asked to select the GitHub account you wish to use to publish your application. If you haven’t already configured a GitHub account, you can do so by pressing the "Add Account" button.

If this is your first time publishing, you’ll need to add an account, by pressing "Add a new account". This will open a dialog where you can enter your GitHub username and personal access token.

You can enter anything you like into the "Account Name" field. This is just for you to identify the account. The "Token" field is where you’ll paste the personal access token that you generated in the previous step.

Press "Save" to save the account, and then press "Continue" to proceed with publishing your application.

While publishing, you’ll see a progress dialog like the one shown below:

If all goes well, you should see a dialog like the one shown below:

You can click on "View Download Page" to view the download page for your application. This page will provide a link to download the installer for your application.

Create New Project

If you are starting from scratch, you can use the "Create New Project" option in the main menu to create a new project based on a selection of templates. Some of the templates available include:

swing - A Swing application
javafx - A JavaFX application
codenameone - A Codename One application
fxgl- An FXGL application

All templates currently use Maven as the build system.

Most of the "Create New Project" dialog should be self-explanatory. You can select the template you want to use, and enter the name of your project. The "Group ID" and "Artifact ID" fields are used to generate the Maven coordinates for your project.

You can select either GitHub or npm as a publish target. If you select GitHub, you’ll need to provide the URL to your GitHub repository. If you select npm, you’ll need to specify the name of your npm package. These options can be configured also later in the project editor.

Press "Create Project" to create your new project. Upon completion, the project editor dialog open, allowing you to configure your application, further.

Tip	You can open the project’s directory in Finder/File explorer by selecting "File" > "Open Project Directory" from the menu.

You can open the project in your preferred IDE.

Deploy as a Web App (CheerpJ)

jDeploy includes support for deploying Java Swing/AWT-based applications as progressive web apps. From the CheerpJ website:

CheerpJ is a WebAssembly-based Java Virtual Machine for the browser. It has extensive compatibility with Java 8 and provides a full runtime environment1 for running Java applications, applets, libraries, and Java Web Start / JNLP applications in the browser without plugins.

This is currently experimental. Limitations include:

Only Swing/AWT UIs are supported currently. No JavaFX.
Some 3rd-party java libraries may not be supported. You can try to build and find out.

Important

Please read the CheerpJ licensing options before deploying your application, to ensure that you are fully compliant.

To preview your app running as a web app, you can press the "Web Preview" button in the project editor dialog. This will build your application as a web app, then open a dialog for you to preview it in your browser, as shown below:

You can open the web preview in your browser by pressing the "Open in Browser" button.

The following screenshot shows the SwingSet2 demo running as a web app in the browser:

The Project Editor Dialog

To do