jDeploy Developer Guide

jDeploy provides a graphical user interface that makes it easy to configure your app’s deployment settings such as icons, splash screens, file associations, etc…​ After you’re satisfied with the settings, press "Publish", and it will publish your app so that users can download the latest version.

If you use IntelliJ IDEA for your IDE, then you may prefer to use the jDeploy IntelliJ Plugin, which provides a project wizard with plug-and-play templates for Swing, Codename One, and JavaFX projects.

When you publish your application using jDeploy, your users will instantly be able to download your app at https://www.jdeploy.com/~YOUR-APP-NAME

The download page includes links for Windows, Mac, and Linux. At time of writing, Linux includes two different download types: .deb, and .bin, but more may be added as there is demand.

The installer that is downloaded from the download page will prompt the user to select relevant installation options, such as whether to add a link in the Dock (Mac only), or the Start Menu (Windows Only), and whether to enable auto-update (default "On").

After selecting the desired options, the user can press the Install button, which will trigger the installation of your app. This will only take a second, and, when complete, the user will be prompted with a dialog as follows:

In this example, clicking on the "Open SwingSet2", will open the app as shown below:

When you deploy your app with jDeploy, you don’t need to sign or notarize it as you normally would when deploying a Mac application. jDeploy handles all of this so you don’t need to worry about it. You don’t require any Apple developer certificates; nor do you require an Apple developer account. Mac users running the latest versions of MacOS will be able to download and install your app, by simply downloading it from the jDeploy download page, and running the installer.

If, however, you do have an Apple Developer account, and want to sign and notarize your app, you can do this as well, via a convenient Github action.

jDeploy currently uses Azul’s OpenJDK REST API to download an appropriate JRE, or JDK on demand. You can specify which version of Java your app requires in your jDeploy config file. You can also specify whether your app requires a full JDK, or JavaFX. Deploying JavaFX apps with jDeploy is actually quite painless - as you don’t need to bundle the JavaFX jars or modules with your distribution.

At time of writing, LTS (long-term-support) Java versions from 8 through 17 are supported.

You can automate your deployments using the jDeploy Github action. Publish your app as a GitHub release, or using npm’s repository.

jDeploy supports hosting your releases on both GitHub (as release artifacts) or npm. When you publish a new version, your app will automatically detect this the next time it is launched, so that you can be sure that your users are always working with your latest version.

The jDeploy GitHub action will allow you to publish native apps that stay in-sync with changes in a particular branch of your repository. When you commit changes to that branch, the app will automatically receive the update the next time it is launched. This all happens through the magic of Github actions.

You can either install jdeploy globally, or locally. When you install it locally, it will only be available to the project that you install it into, and you would run it with npx jdeploy …​. When you install it globally, it will be available in your command-line path no matter where you are.

Installing Globally

Installing Locally

Open a command prompt and navigate to your Java project directory.

Run the jdeploy command. E.g.

If this is your first time using jdeploy on this package, you’ll be prompted to create a package.json file:

Press Yes.

This will open the jDeploy GUI, and it will look something like the following screenshot.

jDeploy will have already tried to generate some sensible settings here, but you should go over them yourself to make sure they are correct.

The most important fields here are:

If you eschew GUIs and prefer to work on the command-line, the following instructions are for you.

In terminal, navigate to a directory containing an executable .jar file that you would like to publish.

This will generate a package.json file with settings to allow you to publish the app to npm.

Such file associations can registered by adding the documentTypes property to the jdeploy object. E.g.

The documentTypes array may contain zero of more object entries, with the following properties:

When a user launches your app by opening an associated file type (e.g. by dragging the file on your app icon, or selecting your app in the "Open with" menu), you will likely want to know which file triggered the launch. On Windows and Linux, these file paths are passed as arguments in your main() method. E.g.

On Macintosh, you need to use the java.awt.Desktop class to be notified when the user opens a file with your app.

To add multiple URL schemes, you can simply add multiple values separated by commas in the text field.

e.g.

"myapp,podcast,feed"

In this case the app would respond to URLs like "myapp:…​", "podcast:…​", and "feed:…​"

You can associate your app with both custom schemes, and standard schemes. For a list of standard URL schemes that you might want your app to be ableto handle, see this wikipedia entry.

Do this by adding a urlSchemes property of the jdeploy object with an array of string schemes.

E.g.:

With the above configuration in the package.json file, your app would be launched when the user clicks links like "jdtext:…​." in a webpage.

E.g.

When a user launches your app by clicking on a link, you will likely want to know the URL that triggered the launch. On Windows and Linux, these URLs paths are passed as arguments in your main() method. E.g.

On Macintosh, you need to use the java.awt.Desktop class to be notified when the user opens a URL with your app.

JVM options are options that configure how the JVM works. They are always marked with the "-X" prefix. Some examples of commonly-used JVM options include:

You can set system properties using the -D prefix. E.g. -Dmyapp.setting=foobar

Arguments that are not prefixed with -X or -D are treated as program arguments. They will be passed to your program, and you can receive them in your main(String[] args) method.

jDeploy supports a handful of placeholder variables that can be embedded in your run arguments, and will be replaced with the appropriate value at runtime. Placeholder variables are marked with {{ varname }}. The available variables are as follows:

In some cases you may want a setting to only be applied on a specific platform. For example some JVM options may be mac specific. jDeploy provides a minimal syntax for marking an argument as platform-specific. For system properties, you would add a condition after the -D prefix, so instead of -Dfoo=bar, you would have -D[CONDITION]foo=bar where CONDITION is one or more platform names ("mac-x64", "mac-arm64", "linux", "win") delimited by pipes. Some examples:

A similar syntax is used for platform-specific JVM options: -X[CONDITION]value, where CONDITION is one or more platform names ("mac-x64", "mac-arm64", "linux", "win") delimited by pipes. Some examples:

Finally, for program arguments (i.e. arguments that are passed to your main(args) method), you can mark them as platform-specific by adding a -[CONDITION] prefix. E.g. -[mac]anArgOnlyAddedOnMac. Some more examples:

To publish your packages on GitHub, you’ll need to add the following to your workflow.

This should be placed in a step after you have built your app already (e.g. using maven, gradle, ant, etc…​).

If this action is used in a workflow on a merge or push, then it will publish artifacts on a release named after the branch that the workflow is running on.

E.g. If this workflow runs on the "master" branch, then it will publish your app bundles as artifacts on a tag named "master".

E.g. https://github.com/shannah/swingset2/releases/tag/master

If this action is used in a workflow on a release or tag action, then it will add the app bundles as artifacts directly on the release/tag in GitHub.

The URL convention for the jDeploy download page for apps hosted on GitHub is:

E.g. The SwingSet app whose repository is located at https://github.com/shannah/swingset2, will have download page at https://www.jdeploy.com/gh/shannah/swingset2.

To access the download page for a specific branch you can append the branch name to the URL. E.g. The download for the "Swing Set 2 (master)" app, which is synchronized with the "master" branch, the URL would be:

By default, MacOS apps are distributed as an installer, which is signed and notarized by jDeploy, so you don’t need to sign it with your own Apple developer certificate. However, if you would prefer to sign the app with your own certificate, you can distribute it as a DMG instead of an installer, you can do this via the jDeploy DMG GitHub action.

The IntelliJ plugin project templates include a DMG job in the GitHub workflow by default, but you do need to define a configuration variable and some secrets in your repository.

For full instructions, see the README.

See: Example release produced by this action.

Your release artifacts must be published to a public repository in order for the jDeploy installer to be able to download updates for your app. If your repository is private, you can publish your releases in a different repository which is public.

Step One: Create a Public Repository for your Releases

For example, consider a scenario where your app is in the private repository yourname/yourapp. Then you could create a new public repository at yourname/yourapp-releases.

Step Two: Create a Personal Access Token

In order to publish releases to a different repository, you’ll need to create a personal access token that has permission to create releases in the other repository.

Learn more about personal access tokens.

Once you’ve created the personal access token, you’ll need to add it as a secret in your repository.

Step Three: Specify the target_repository in your workflow

Finally, you’ll need to modify the invocation of the jdeploy GitHub action to use the target_repository parameter, and change the github_token parameter to use your personal access token instead of the default github_token.

The next time your run the workflow, it should publish the releases to the yourapp-releases repository instead of the yourapp repository.

This action will add (and update) a tag named "jdeploy" to your repo, with a file named "package-info.json". This tag must not be deleted. The package-info.json file is used by both the jDeploy launcher and installer obtain details about your app, so that it knows what versions are available.

If you’re starting out with a new JavaFX project, then the jdeploy-javafx-starter may be what you’re looking for. It provides you with a bare-bones JavaFX maven project, based on the official openjfx javafx-archetype-simple archtype, but it comes loaded with a GitHub workflow to auto-generate native installers for all branches and releases.

Getting started is as simple as pressing "Use this template", and you’ll be all set.

See https://github.com/shannah/jdeploy-javafx-starter for details.

The two most common strategies to produce executable jars in Maven are using either a combination of the maven-dependency-plugin and the maven-jar-plugin, or using the maven-assembly-plugin. The latter approach (maven-assembly-plugin) can generate a single "fat" jar with all of your dependencies. The former approach (maven-dependency-plugin and maven-jar-plugin) places your dependencies in a "libs" directory.

In Maven, for example, you will need to use the the maven-dependency-plugin and maven-jar-plugin plugins to package up all the dependencies, and add the appropriate manifest entries to make the jar executable. The following snippet can be added to the <build>/<plugins> section of your pom.xml file.

You will need to change the <mainClass>com.example.YourMainClass</mainClass> entry to point to the main class of your app.

The maven-assembly-plugin is an alternate way to produce an executable jar. It will generate a "fat" jar with all dependencies.

The following snippet can be added to the <build>/<plugins> section of your pom.xml file.

You will need to change the <mainClass>com.example.YourMainClass</mainClass> entry to point to the main class of your app.

Given an application with package name "myapp" and title "My App", the following file structure will be created on Windows:

If the app uses Java 8:

If the app uses Java 11 or higher:

The layout for apps deployed via GitHub releases is slightly different. The main difference is that the app is installed in a directory that is named after the hash of the app’s package name and version. This is to ensure that multiple versions of the same app can be installed side-by-side. Each app has a unique hash prefix that is derived from the package name and version of the app. This hash prefix is used to create a unique directory for the app. In addition, the package is installed in the %HOMEPATH%/.jdeploy/gh-packages directory, rather than the %HOMEPATH%/.jdeploy/packages directory.

If the app uses Java 8:

If the app uses Java 11 or higher: