Getting Started with jDeploy for Command-line Apps

This tutorial describes how to use jDeploy to deploy a Java command-line application using npm. jDeploy can also be used to deploy GUI Desktop applications. See the jDeploy developers guide for more information about GUI Desktop distribution.

jDeploy allows you to deploy Java applications using NPM. In a nutshell:

  1. You have an executable Jar file, or a War file.

  2. Run jdeploy publish.

  3. Your app can now be installed on any computer that has NodeJS installed by simply typing npm install my-app.

Example 1: Hello World

Create a new "Java Application" project in Netbeans and create a simple app that just prints "Hello World" to System.out. The main class might look something like:

package com.example.hello;
public class HelloWorld {
    public static void main (String[] args) {
        System.out.println("Hello World");

Build the app. This should produce an executable Jar file in your "dist" directory. In my case dist/hello.jar.

Now open a command prompt and navigate to the directory of your project:

$ cd /path/to/helloworld

Creating the jDeploy Project:

First we need to initialize the jdeploy project:

$ jdeploy init

This will generate a package.json file in your project directory.

Open this file to take a look at the defaults. Most of the properties in this file are just standard properties for an NPM project. There are three properties that we’ll look at here that are relevant to our deployment.

  1. "name" - This is the name of our project as it will be listed in the NPM registry. This name must be unique. If you try to publish a project with a name that is already registered by someone else, it will fail. This name will be used by users who want to install your app. E.g. If "name"= "hello-world", then people would install my app by typing "npm install hello-world -g" at the command prompt.

  2. "bin" - This specifies the name of the command that will be installed to activate your app. It actually maps an alias to the "jdeploy-bundle/jdeploy.js" script, which is thin bootstrap shell script for your java app. The entry will look like "bin" : {"hello-world" : "jdeploy-bundle/jdeploy.js"}. If you want to change your app’s command name to "my-hello-world", then you would just change "hello-world" to "my-hello-world".

  3. "jdeploy" - This includes a number of jdeploy-specific properties. In our case it has a "jar" sub-property that points to the location of the executable Jar that contains our application.

Installing the App on Local Machine

Installing the app on your local machine can be achieved with:

$ jdeploy install

This packages up the app, and links it to your PATH so that you can now run your app directly from the command prompt by simply typing "hello-world".

$ hello-world
Hello World!

Publishing the App to NPM

Publishing the app to NPM requires an NPM account. This takes a few seconds to set up. You can simply type npm adduser and follow the prompts. full instructions on the NPM site. If you already have an account but haven’t logged in on the current machine you would use npm login to login and store the credentials locally.

Then just type

$ jdeploy publish
If you have already just run jdeploy package or jdeploy install, you could just run npm publish and it would accomplish the same thing. Calling jdeploy publish will first package the app, and then call npm publish behind the scenes.

Installing the App on another Machine

Now that your app has been published, we can go to any machine that has NodeJS installed, and type:

$ npm install hello-world -g

And it will install your app:

On Mac and Linux you’ll need to use sudo as it adds a symlink to /usr/local/bin which requires sudo permissions. On Windows it will work without sudo as long as you are using an Administrator account.

You can then run it with

$ hello-world