Customizing the JDK

Last updated 16 May 2016

There are some cases where files need to be bundled with the JDK in order to expose functionality in the runtime JVM. For example, the inclusion of unlimited strength Java Cryptography Extensions (JCE) is often added to a JDK in order to utilize stronger cryptographic libraries. To handle such cases, Heroku will copy files designated by the app in a .jdk-overlay folder into the JDK’s directory structure.

To include additional files in the JVM, follow these instructions:

Prerequisites

• A Java app running on Heroku.

Specify a JDK Version

Create a system.properties file if one does not already exist, specify the version, and commit it to git. Versions 1.6, 1.7, and 1.8 are supported.

$ echo "java.runtime.version=1.7" > system.properties
$ git add system.properties
$ git commit -m "JDK 7"

Create a .jdk-overlay Folder

In your application’s root directory, create a .jdk-overlay folder.

$ mkdir .jdk-overlay
$ ls -la
total 24
drwxr-xr-x    9 user  staff   306 Oct 16 14:43 .
drwxr-xr-x  202 user  staff  6868 Oct 16 14:40 ..
drwxr-xr-x   13 user  staff   442 Oct 16 15:06 .git
drwxr-xr-x    3 user  staff   102 Oct 16 14:43 .jdk-overlay
-rw-r--r--    1 user  staff    45 Oct 16 14:40 Procfile
-rw-r--r--    1 user  staff  1860 Oct 16 14:40 pom.xml
drwxr-xr-x    3 user  staff   102 Oct 16 14:40 src
-rw-r--r--    1 user  staff    25 Oct 16 14:40 system.properties

Add Custom Files

Copy any custom files into the .jdk-overlay file. The files will be copied to their equivalent directory in the JDK. For example, to define a custom security policy, the java.policy file could be placed in the .jdk-overlay/jre/lib/security/ directory of your app’s repository.

You may also need to add custom certificates to the JDK’s cacerts. You may start with the keystore in your local JDK or download the base Heroku keystore. After adding the custom certificate with a command like this:

$ keytool -import -keystore cacerts -file custom.cer

You may then include the keystore in the slug by placing it in the .jdk-overlay/jre/lib/security/ directory of your app’s repository.

Now add any custom files to your Git repo like this:

$ git add .jdk-overlay
$ git commit -m "Custom JDK Files"

Then deploy your application, with the custom files, to Heroku:

$ git push heroku master
...

Verify the Copy

The copies can be verified by starting a bash session on Heroku and checking the JDK directory. The JDK directory is located in $HOME/.jdk/.

For example, to verify custom certificates were copied correctly, the $HOME/.jdk/jre/lib/security/ directory can be checked.

$ heroku run bash
Running `bash` attached to terminal... up, run.1
~ $ keytool -list -keystore .jdk/jre/lib/security/cacerts
...
Your keystore contains 140 entries
...

Other Examples

This method can be used for Java extensions when necessary. Though a dependency management tool, such as Maven, should be the preferred mechanism for introducing dependencies.