Skip to content

Running Payara Micro services on Heroku is incredibly straightforward.

There are 2 basic ways of running a Payara Micro service on Heroku:

  1. Create a Fat Jar
  2. Deploy a .War file along with PayaraMicro.jar

I prefer to deploy applications as .War files rather than Fat Jars, so in this example, I'll show how to create a Heroku application and deploy a Payara Micro service to it.

Enabling a Payara Micro Application For Heroku

To enable a Payara Micro application for running on Heroku, there are two simple steps we have to make. The first is to simply bundle the Payara Micro distribution file within the Maven project. (You could create a standalone app and completely use Maven, but I think this is a simpler solution). Download Payara Micro and place it in the \lib folder of the Maven project.

.
|___.gitignore
|___lib
| |___payara-micro-4.1.1.164.jar
|___pom.xml
|___Procfile
|___src
| |___main
| | |___java

The reason for deploying Payara Micro is simply that we need this to launch any service .War files. *Remember, we could use a Fat Jar, if that's your preference.*

Secondly, we need to create a file telling Heroku how to run the service that we are to deploy. This file, Procfile needs to be created at the root of the Maven project structure as shown above. The contents of this file tell Heroku how to start Payara Micro and deploy the application:

web:    java -jar lib/payara-micro-4.1.1.164.jar 
--deploy target/PayaraHeroku.war --port $PORT

There are a few things to say about the Procfile. You can see that this defines a web application that is invoked by java -jar lib/payara-micro-4.1.1.164.jar. There are then a couple of Payara Micro command line options. --deploy tells Payara Micro to deploy the result of the Maven build (target/PayaraHeroku.war in this example). --port $PORT tells Payara Micro to listen on the correct port that Heroku is using

So that's it, there are only 2 small changes needed to a Payara Micro service to enable it to run on Heroku. We need to add the Payara Micro runtime and create a Procfile.

Deploying a Heroku Application

Once you've created a Payara Micro application, it needs to be deployed on Heroku. Deploying a Heroku application is documented in depth on the Heroku Dev Centre. You'll find everything you need to know about deploying Java applications there, so I'll only go over this briefly.

The basic steps are to:

  1. Create a Heroku Application heroku create
  2. Commit your Payara Micro service git add ... && git commit ...
  3. Push the git repository to Heroku git push heroku master
  4. Scale the application accordingly heroku ps:scale web=1

Once the git repository is pushed to Heroku, Heroku will work out that this is a Java application and will start the Maven build. This will create the artefact in the target directory on Heroku which is referenced by the Procfile. Once the build is complete, Heroku will start the Payara Micro service using the options defined within the Procfile.

And that's it! As you can see, there's very little you need to do to be able to get your Payara Micro services running on Heroku.

When deploying an application to Payara Micro, the default context path for any web resources is defined by the name of the archive.

For example, if I deploy the archive PayaraRest-1.0-SNAPSHOT.war, the context root is defined as /PayaraRest-1.0-SNAPSHOT

$ java -jar payara-micro.jar --deploy  PayaraRest-1.0-SNAPSHOT.war
 ...
[Payara Micro 4.1]  Loading application [PayaraRest-1.0-SNAPSHOT] at [/PayaraRest-1.0-SNAPSHOT]

There are a few techniques however for changing the context of deployed applications in Payara Micro.

File Name

The simplest way of changing the context of a deployed application is to change the name of the archive being deployed. The context will be set to the name of the archive, for example:

$ mv target/PayaraRest-1.0-SNAPSHOT.war target/Renamed.war

$ java -jar payara-micro.jar --deploy target\Renamed.war
 ...
[Payara Micro 4.1]  Loading application [Renamed] at [/Renamed]

glassfish-web.xml

The context of a web application can also be changed using the standard Payara configuration xml, by adding an entry into the glassfish-web.xml file within the project.

<glassfish-web-app error-url="">
    <context-root>/PayaraRest</context-root>
</glassfish-web-app>
$ java -jar payara-micro.jar --deploy  PayaraRest-1.0-SNAPSHOT
 ...
[Payara Micro 4.1] Loading application [PayaraRest-1.0-SNAPSHOT] at [/PayaraRest]

Deploying via Code

Using Java code, it's relatively straightforward to deploy an application using a few lines of code. First of all, add the dependencies to Payara Micro into your pom.xml

<dependency>
    <groupId>fish.payara.extras</groupId>
    <artifactId>payara-micro</artifactId>
    <version>4.1.153</version>
    <type>jar</type>
</dependency>

Applications can then be deployed by creating an instance of a PayaraMicroRuntime and calling its deploy() method. This method takes the name and the context path to deploy:

package com.davidsalter.payaradeployer;

import fish.payara.micro.PayaraMicro;
import fish.payara.micro.PayaraMicroRuntime;
import java.io.FileInputStream;
import java.io.InputStream;

public class Main {

    public static void main(String[] args) throws Exception {
        PayaraMicroRuntime instance = PayaraMicro.bootstrap();
        InputStream is = new FileInputStream("<path to>\PayaraRest-1.0-SNAPSHOT.war");
        instance.deploy("PayaraRest", "Programatically", is);
    }
}
 ...
[Payara 4.1] Loading application [PayaraRest] at [/Programatically]

/ Deployments

One final point to note is that if you wish to deploy an application at the root context /, this can be achieved by renaming the deployment ROOT.war

$ mv target/PayaraRest-1.0-SNAPSHOT.war target/ROOT.war

$ java -jar payara-micro.jar --deploy target\ROOT.war
 ...
[Payara Micro 4.1] Loading application [ROOT] at [/]

Conclusion

In this article, I've shown a few different techniques for changing the deployment context for web applications in Payara Micro. Hopefully you'll agree that these simple techniques can allow you to make useful changes to your microservice deployments.

There are many different frameworks that allow you to develop and deploy microservices. Payara, the team behind the Payara Server have a couple of options for deploying microservices - PayaraMicro and Payara MicroProfile. So, what exactly are PayaraMicro and Payara MicroProfile?

What is Payara Micro?

Both PayaraMicro and Payara Microprofile are small .jar files that allow you to deploy .war files from the command line allowing Java EE applications to be easily executed.

PayaraMicro is described as:

small, <70 MB in size and incredibly simple to use. With its automatic and elastic clustering, Payara Micro is designed for running Java EE applications in a modern containerized/ virtualized infrastructure, using automated provisioning tools like Chef, Ansible or Puppet.

and supports the following Java EE APIs.

  • Servlets, JSTL, EL and JSPs
  • WebSockets
  • JSF
  • JAX-RS
  • EJB lite
  • JTA
  • JPA
  • Bean Validation
  • CDI
  • Interceptors
  • JBatch
  • Concurrency
  • JCache

Payara MicroProfile follows the MicroProfile initiative led by IBM, the London Java Community, RedHat, TomiTribe, Payara and SOUJava and provides support for the following APIs.

  • JSON-P
  • CDI
  • JAX-RS

Essentially, Payara MicroProfile is a cut down version of Payara Micro.

OK, so we've got a pretty good understanding of what Payara Micro / MicroProfile are, but how can they be used to deploy Java EE applications?

Downloading Payara Micro

Both installations can be downloaded as a .jar file from Payara's web site. The downloads are based on the full version of Payara Server, which is in turn based on the latest version of GlassFish 4.

Deploying onto Payara Micro

To deploy and run an application using Payara Micro (from hereon, when I refer to Payara Micro, I mean Payara Micro or Payara MicroProfile), we execute Payara Micro and tell it to deploy the application. This is different from technologies such as WildFly Swarm, which requires application specific APIs to develop and deploy the application.

For example, to deploy a JAX-RS application in WildFly Swarm, we need to build and deploy with the appropriate Swarm artifacts:

<dependency>  
  <groupId>org.wildfly.swarm</groupId>
  <artifactId>wildfly-swarm-jaxrs</artifactId>
  <version>${swarm.version}</version>
</dependency>

With Payara Micro, this is not necessary - the only dependency we have is Java EE itself.

<dependency>
  <groupId>javax</groupId>
  <artifactId>javaee-web-api</artifactId>
  <version>7.0</version>
  <scope>provided</scope>
</dependency>

Starting up Payara Micro and deploying an application is a case of executing the following command:

java -jar payara-micro-4.1.1.164.jar --deploy <app.war

where <app.war> is the path to the .war file to deploy.

...
[2016-12-29T21:41:37.471+0000] [Payara Micro 4.1] [INFO] [] [PayaraMicro] [tid: _ThreadID=1 _ThreadName=main] [timeMillis: 1483090897471] [levelValue: 800] Deployed 1 archives

[2016-12-29T21:41:37.472+0000] [Payara Micro 4.1] [INFO] [] [PayaraMicro] [tid: _ThreadID=1 _ThreadName=main] [timeMillis: 1483090897472] [levelValue: 800] Payara Micro  4.1.1.164 #badassmicrofish (build 28) ready in 17990 (ms)

That's all there is to it. We can easily start Payara Micro and deploy a .war file to it without having to add any specific MicroProfile content into the codebase.

As a word of caution, it's worth noting the APIs that Payara Micro supports however. For example, if you try to use JAX-WS, the chances are your application won't deploy and won't work! Stick to the supported API's and you should be ok.

Creating an UberJar Distribution

We've just seen how to start and deploy an application using Payara Micro. We can also use Payara Micro to create an UberJar if we wish to distribute applications as a single .jar

Creating the UberJar is simply a matter of appending the relevant command line parameters onto Payara Micro.

$ java -jar payara-micro-4.1.1.164.jar --deploy <app.war> --outputUberJar MyApp.jar
Dec 29, 2016 22:12:58 AM fish.payara.micro.PayaraMicro packageUberJar
INFO: Building Uber Jar... MyApp.jar
Dec 29, 2016 22:13:14 AM fish.payara.micro.PayaraMicro packageUberJar
INFO: Built Uber Jar MyApp.jar in 15439 (ms)

Command Line Options

In this post, we've just looked at a couple of the command line parameters to Payara Micro (--deploy and --outputUberJar). There are many more parameters that can be used for example, setting the HTTP port or maximum number of HTTP threads. Details of these options are provided on the Payara Micro wiki

Conclusion

Payara Micro is a lightweight way of executing Java EE applications supporting the relevant APIs. It's easy to use, but provides flexibility and many of the features of it's big brother - Payara Server.