Last updated September 29, 2023

This article describes how to take an existing Java app and deploy it to Heroku.

Prerequisites

The best practices in this article assume that you have:

• an existing Java app that uses Maven as a build tool.
• a free Heroku account
• the Heroku CLI
• a Java JDK
• Maven 3

Overview

The details of Heroku’s Java Support are described in the Heroku Java Support article.

Heroku Java support for Maven will be applied to applications that contain a pom.xml file.

Verify that your pom.xml file is set up correctly

If your app has any dependencies, the pom.xml file should include the maven-dependency-plugin. It tells Maven to copy the jar files that your app depends on to the target/dependency directory. This way, they are put into the slug, and the .m2 directory can be removed from the slug. It should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <version>1.0-SNAPSHOT</version>
    <artifactId>helloworld</artifactId>
    <dependencies>
        ...
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.0.1</version>
                <executions>
                    <execution>
                        <id>copy-dependencies</id>
                        <phase>package</phase>
                        <goals><goal>copy-dependencies</goal></goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Specify a JDK

Optionally, you can specify a JDK. For more information, see Specifying a Java version.

The Procfile

A Procfile is a text file in the root directory of your application, that defines process types and explicitly declares what command should be executed to start your app. Your Procfile will look something like this:

web: java $JAVA_OPTS -cp target/classes:target/dependency/* com.example.HelloWorld

This declares a single process type, web, and the command needed to run it. The name, web, is important here. It declares that this process type will be attached to the HTTP routing stack of Heroku, and receive web traffic when deployed.

The command in a web process type must bind to the port number specified in the PORT environment variable. If it does not, the dyno will not start.

How to keep build artifacts out of git

Prevent build artifacts from going into revision control by creating a .gitignore file. Here’s a typical .gitignore file:

target

Build your app and run it locally

To build your app locally do this:

$ mvn clean install
$ heroku local --port 5001

Your app should now be running on http://localhost:5001/.

Deploy your application to Heroku

After you commit your changes to git, you can deploy your app to Heroku.

$ git add .
$ git commit -m "Added a Procfile."
$ heroku login
Enter your Heroku credentials.
...
$ heroku create
Creating arcane-lowlands-8408... done, stack is heroku-18
http://arcane-lowlands-8408.herokuapp.com/ | git@heroku.com:arcane-lowlands-8408.git
Git remote heroku added
$ git push heroku main
...
-----> Java app detected
...
-----> Launching... done
       http://arcane-lowlands-8408.herokuapp.com deployed to Heroku

To open the app in your browser, type heroku open.