Java buildpack

Page last updated:

You can use the Java buildpack with apps written in Grails, Play, Spring, or any other JVM-based language or framework.

For information about specific versions, see Java Buildpack Release Notes. You can find the source for the Java buildpack in the Java buildpack repository on GitHub.

Java buildpack v5 and later is written in Go and replaces the earlier Ruby-based buildpack. It supports the same JBP_CONFIG_* configuration overrides. For the differences, see the Ruby vs. Go Java buildpack comparison. For the documentation of the Ruby-based Java buildpack, see the Java buildpack v4.77.0 repository on GitHub.

Buildpack and application logging

The Java buildpack only runs during the staging process, and only logs staging information such as the downloaded components, configuration data, and work performed on your application by the buildpack.

The Java buildpack writes its messages to the staging output. You can see the staging output when you run cf push, or later by running cf logs APP-NAME --recent. The buildpack does not write a log file to the app directory.

To include debug messages in the staging output, set the BP_DEBUG environment variable and restage your app:

cf set-env APP-NAME BP_DEBUG true
cf restage APP-NAME

Only the presence of BP_DEBUG counts: any non-empty value enables debug messages during staging, including false, 0, OFF, or NONE. To disable debug messages, unset the variable and restage your app:

cf unset-env APP-NAME BP_DEBUG
cf restage APP-NAME

Note If you set BP_DEBUG in the env block of your manifest.yml file, removing it from the manifest does not unset it. Run cf unset-env to remove it. For more information, see Environment variables in App manifest attribute reference.

Once staging completes, the buildpack stops logging then the Loggregator handles application logging.

Your application must write to STDOUT or STDERR for its logs to be included in the Loggregator stream. For more information about logging, see App Logging in Cloud Foundry.

BOSH custom trusted certificate support

Versions 3.7 and later of the Java buildpack support BOSH configured custom trusted certificates. For more information, see Configuring Trusted Certificates in the BOSH documentation.

The Java buildpack pulls the contents of /etc/ssl/certs/ca-certificates.crt and $CF_INSTANCE_CERT/$CF_INSTANCE_KEY by default.

The log output for Diego Instance Identity-based KeyStore appears as follows:

Adding System Key Manager
Adding Key Manager for /etc/cf-instance-credentials/instance.key and /etc/cf-instance-credentials/instance.crt
Start watching /etc/cf-instance-credentials/instance.crt
Start watching /etc/cf-instance-credentials/instance.key
Initialized KeyManager for /etc/cf-instance-credentials/instance.key and /etc/cf-instance-credentials/instance.crt

The log output for Diego Trusted Certificate-based TrustStore appears as follows:

Adding System Trust Manager
Adding TrustManager for /etc/ssl/certs/ca-certificates.crt
Start watching /etc/ssl/certs/ca-certificates.crt
Initialized TrustManager for /etc/ssl/certs/ca-certificates.crt

Memory constraints

The memory calculator in the Java buildpack accounts for the following memory regions:

• -Xmx: Heap
• -XX:MaxMetaspaceSize: Metaspace
• -Xss: Thread Stacks
• -XX:MaxDirectMemorySize: Direct Memory
• -XX:ReservedCodeCacheSize: Code Cache

Most applications run if they use the Cloud Foundry default container size of 1 G without any modifications. However, you can configure the non-heap memory regions and the memory calculator settings as needed.

The Java buildpack optimizes for all non-heap memory regions first and leaves the remainder for the heap.

Note Preferably do not set the heap size with -Xmx in JAVA_OPTS. Let the memory calculator size the heap. To give the app more or less memory, change the container memory of the app. To tune the calculation, use the memory calculator settings, or in special cases set a specific non-heap memory region, such as -XX:MaxDirectMemorySize, in JAVA_OPTS. For more information, see Upgrading from Java buildpack v4.x.

The Java buildpack prints a histogram of the heap to the logs when the JVM encounters a terminal failure.

Upgrading from Java buildpack v4.x

Java buildpack v5 uses version 4 of the memory calculator. Java buildpack v4.x used version 3. The difference only affects apps that set -Xmx explicitly in JAVA_OPTS:

• Version 3 fitted the non-heap memory regions into the memory left over after -Xmx.
• Version 4 calculates the non-heap memory regions independently, and requires that the heap and non-heap memory together fit in the container.

As a result, an app with an explicit -Xmx that started in a container with v4.x of the buildpack might fail to start with v5, with an error like the following:

required memory 1133652K is greater than 750M available for allocation: -XX:MaxDirectMemorySize=10M, -Xmx512M, -XX:MaxMetaspaceSize=97364K, -XX:ReservedCodeCacheSize=240M, -Xss1M x 250 threads

Preferably do not set -Xmx in JAVA_OPTS. Let the memory calculator size the heap from the memory that remains after the non-heap memory regions. To change how much memory the app gets, use the following options instead:

• Set the container memory for the app, for example with memory: in your manifest.yml file. The memory calculator sizes the heap to fit.

• Adjust the memory calculator settings. For example, if your app uses fewer threads than the default of 250, lower the number of threads that the memory calculator reserves stack memory for. This leaves more memory for the heap:

  cf set-env APP-NAME JBP_CONFIG_OPEN_JDK_JRE '{ memory_calculator: { stack_threads: 50 } }'
  

• In special cases, set a specific non-heap memory region in JAVA_OPTS, for example -XX:MaxDirectMemorySize=64M. The memory calculator uses the values that you set and sizes the remaining regions and the heap around them.

For more information, see the OpenJDK JRE documentation for the Java buildpack.