Running Jersey 2 Applications on Heroku

In this article we’ll create a simple Jersey application deploy it in Jetty servlet container and everything will be hosted on Heroku.

Create an Application

To create a skeleton of Jersey 2 web-app that can be run on Heroku from the jersey-heroku-webapp archetype (available since Jersey 2.5), execute the following Maven command in the directory where you want the new project should be located:

Adjust the groupIdpackage and/or artifactId of your new web application project to your needs or, alternatively, you can change it by updating the new project pom.xml once it gets generated.

Once the project generation from a Jersey maven archetype is successfully finished, you should see the new simple-heroku-webapp project directory created in your current location. The directory contains a standard Maven project structure:

  • src/main/java – project sources
  • src/main/resources – project resources
  • src/main/webapp – project web application files
  • src/test/java – project test-sources (based on JerseyTest)
  • pom.xml – project build and management configuration
  • system.properties – Heroku system properties (OpenJDK version)
  • Procfile – lists of the process types in an application for Heroku

The project (simple-heroku-webapp) contains one JAX-RS resource class, MyResouce, and one resource method which returns simple text message. To make sure the resource is properly tested there is also an end-to-end test-case in MyResourceTest (the test is based on JerseyTest from our Jersey Test Framework). The project contains the standard Java EE web application web.xml deployment descriptor under src/main/webapp/WEB-INF since the goal is to deploy the application in a Servlet container (in our case the application will run in Jetty on Heroku).

To compile and package the application into a WAR, invoke the following maven command in your console:

A successful build output will produce an output similar to the one below:

Now when you know that everything went as expected you are ready to:

  • make some changes in your project,
  • take the packaged WAR (located under ./target/simple-service-webapp.war) and deploy it to a Servlet container of your choice, or
  • deploy it on Heroku

If you want to make some changes to your application you can run the application locally by simply running mvn clean package jetty:run (which starts the embedded Jetty server) or by java -cp target/classes:target/dependency/* com.example.heroku.Main (this is how Jetty is started on Heroku).

Deploy it on Heroku

I don’t want to go into details how to create an account on Heroku and setup the tools on your machine. You can find a lot of useful information in this article: Getting Started with Java on Heroku. Instead, let’s take a look at the steps needed after your environment is ready.

The first step is to create a Git repository from your project:

Then, create Heroku application from the project and add a remote reference to your Git repository:

I’ve changed the name of the instance in the output to simple-heroku-webapp. Yours will be named more like tranquil-basin-4744.

Add and commit files to your Git repository:

Push changes to Heroku:

Now you can access your application at, for example: http://simple-heroku-webapp.herokuapp.com/myresource

Or take a look at the WADL of the app, at http://simple-heroku-webapp.herokuapp.com/application.wadl:

Resources

GitHub project: mgajdos/jersey-simple-heroku-webapp (zip)
Deployed app: http://simple-heroku-webapp.herokuapp.com/myresource
Archetype on GitHub: jersey/archetypes/jersey-heroku-webapp

Further reading

Jersey User Guide