GitHub Readme.md
This plugin is used to deploy Java applications directly to Heroku without pushing to a Git repository. It uses Heroku's Platform API. This is can be useful when deploying from a CI server, deploying pre-built JAR or WAR files.
The plugin has two main goals:
heroku:deploy
and heroku:deploy-only
for deploying standalone applicationsheroku:deploy-war
for deploying WAR filesIn addition to those two main goals, three additional goals are available:
heroku:dashboard
to open the Heroku dashboard for the configured applicationheroku:run-war
to locally running WAR filesheroku:eclipse-launch-config
to generate launch configurations for Eclipse IDEThis plugin uses Heroku's Platform API and thus requires an API key to function. If you have the
Heroku CLI installed and logged in with heroku login
, the plugin will automatically
pick up your API key. Alternatively, you can use the HEROKU_API_KEY
environment variable to set your API key:
$ HEROKU_API_KEY="xxx-xxx-xxxx" mvn heroku:deploy
Add the following to your pom.xml
, but replace the <web>
element with the command used to run your application.
<build>
<plugins>
<plugin>
<groupId>com.heroku.sdk</groupId>
<artifactId>heroku-maven-plugin</artifactId>
<version>3.0.4</version>
<configuration>
<appName>${heroku.appName}</appName>
<processTypes>
<web>java $JAVA_OPTS -cp target/classes:target/dependency/* com.example.Main</web>
</processTypes>
</configuration>
</plugin>
</plugins>
</build>
You can then run the following command to deploy your application:
$ mvn heroku:deploy
NOTE: This requires that you use <packaging>war</packaging>
in your pom.xml
.
Add the following to your pom.xml
.
<build>
<plugins>
<plugin>
<groupId>com.heroku.sdk</groupId>
<artifactId>heroku-maven-plugin</artifactId>
<version>3.0.4</version>
<configuration>
<appName>${heroku.appName}</appName>
</configuration>
</plugin>
</plugins>
</build>
This assumes your project will generate a WAR file in the target
directory. If the WAR file is located somewhere else,
you can specify this with the <warFile>
configuration element. The <processTypes>
element is not needed
and will be ignored because the plugin will determine the appropriate process type for you.
You can then run the following command to deploy your application:
$ mvn heroku:deploy-war
You can execute your WAR file locally by running the following command:
$ mvn heroku:run-war
This will start the web application in a way that is very similar to how it is run on Heroku. If you need more control over how the WAR file is being run, you can use webapp-runner directly.
In most real-world scenarios, you will need to deploy your application to dev, test and prod environments. There are several ways of handling this.
Use a profile for each app, and configure the plugin accordingly. For example:
<build>
<plugins>
<plugin>
<groupId>com.heroku.sdk</groupId>
<artifactId>heroku-maven-plugin</artifactId>
<version>3.0.4</version>
<configuration>
<processTypes>
<web>java $JAVA_OPTS -cp target/classes:target/dependency/* Main</web>
</processTypes>
</configuration>
</plugin>
</plugins>
</build>
<profiles>
<profile>
<id>test</id>
<build>
<plugins>
<plugin>
<groupId>com.heroku.sdk</groupId>
<artifactId>heroku-maven-plugin</artifactId>
<configuration>
<appName>myapp-test</appName>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>prod</id>
<build>
<plugins>
<plugin>
<groupId>com.heroku.sdk</groupId>
<artifactId>heroku-maven-plugin</artifactId>
<configuration>
<appName>myapp-prod</appName>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
You can provide the application name as a system property like this:
$ mvn heroku:deploy -Dheroku.appName=myapp
This solution is best when multiple developers each need their own apps.
Create a heroku.properties
file in the root directory of your application and put the following code in it
(but replace "myapp" with the name of your Heroku application):
heroku.appName=myapp
Then add the file to your .gitignore
so that each developer can have their own local versions of the file.
The value in heroku.properties
will take precedence over anything configured in your pom.xml
.
The name of the application to deploy.
<appName>my-app-name</appName>
The plugin will detect the appName from the following places in this order:
heroku.properties
fileheroku.appName
system propertyFor example, if you specify the heroku.appName
system property, the Maven configuration shown above will have
no effect. This is useful for deploying multiple apps.
The JDK version to use for your application.
<jdkVersion>11</jdkVersion>
The plugin will look for the required JDK version in the following places, in order:
heroku.jdkVersion
system propertyjava.runtime.version
in system.properties
located in the root directory of your projectFor valid values and the current default, refer to Heroku's DevCenter article about specifing a Java version.
Sets configuration variables for the application on each deploy.
<configVars>
<MY_VAR>SomeValue</MY_VAR>
<JAVA_OPTS>-Xss512k -XX:+UseCompressedOops</JAVA_OPTS>
</configVars>
Any variable defined in configVars
will override defaults and previously defined config variables.
Note: If you adhere to the principles of the 12 Factor app, configuration should be strictly separated from code.
Thus, you do not want to tie your configuration to your codebase. There are a few exceptions to this, like some JAVA_OPTS may be universal.
If possible, you should not use configVars
at all.
Allows you to include additional files and directories.
<includes>
<include>etc/readme.txt</include>
</includes>
Included files and directories must be located within your project root directory.
Allows you to disable automatic inclusion of the target
directory. (Default is true
)
<includeTarget>false</includeTarget>
This is useful in cases where you build a single fat JAR with all dependencies you want to deploy.
Enables or disables logging of the source blob upload progress. (Default is false
)
<logProgress>true</logProgress>
Enabling this will log the upload progress status at DEBUG
level.
Defines the buildpacks used by your application.
<buildpacks>
<buildpack>https://github.com/DuckyTeam/heroku-buildpack-imagemagick</buildpack>
<buildpack>heroku/jvm</buildpack>
</buildpacks>
It can sometimes be useful to use more than just the default heroku/jvm
buildpack for your application. In the above
example, you can see how an additional buildpack is used to install imagemagick.
You can also define your buildpacks using the Heroku Dashboard or the Heroku CLI (i.e. the heroku buildpacks
command).
Adds process types to the generated Procfile for your application.
<processTypes>
<web>java $JAVA_OPTS -cp target/classes:target/dependency/* Main</web>
<worker>java $JAVA_OPTS -cp target/classes:target/dependency/* Worker</worker>
</processTypes>
The plugin will generate a Procfile
for your application and include it. You can use this configuration to add more
process types. It will also pick up entries in the Procfile
within your project root directory, but the plugin configuration
will take precedence.
Specifies the WAR file to use for heroku:deploy-war
and heroku:run-war
goals.
<warFile>custom/directory/webapp.war</warFile>
Normally, the plugin looks for a WAR file in target
and deploys it. This means you usually don't have to configure
this, unless you want to deploy a WAR file located somewhere else.
Configures the version of webapp-runner to use for heroku:deploy-war
and heroku:run-war
.
<webappRunnerVersion>9.0.30.0</webappRunnerVersion>
You can customize the JDK by creating a .jdk-overlay
directory as described in this Dev Center article.
This plugin will automatically include this directory if present.
To run the entire suite of integration tests, use the following command:
$ ./mvnw clean install -Pit
To run an individual integration test, use a command like this:
$ ./mvnw clean install -Pit -Dinvoker.test=simple-deploy-test
Copy the snippet above into CLI.