This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Java Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Java Buildpack How To documentation.
The Paketo Java Buildpack allows users to create an image containing a JVM application from a precompiled artifact or directly from source.
The Java Buildpack is a composite buildpack and each step in a build is handled by one of its components. For a full set of configuration options and capabilities see the homepages for the component buildpacks.
The Java Buildpack uses the BellSoft Liberica implementations of the JRE and JDK. JVM installation is handled by the BellSoft Liberica Buildpack. The JDK will be installed in the build container but only the JRE will be contributed to the application image.
See the homepage for the BellSoft Liberica Buildpack for a full set of configuration options.
The Java Memory Calculator is a tool used by the Paketo Java Buildpack to provide an optimized memory configuration for Java applications running in containers with enforced memory limits.
This section describes the algorithm that is responsible for providing this memory configuration, including the inputs used and their default values.
The Heap memory value, ultimately supplied as the
-xmX JVM flag, is calculated using the following formula:
Heap = Total Container Memory - Non-Heap - Headroom
The Total Container Memory value is the total memory available to the application, typically the value of the memory limit set for the container.
The Non-Heap value is calculated by the algorithm using the following formula.
Non-Heap = Direct Memory + Metaspace + Reserved Code Cache + (Thread Stack * Thread Count)
Headroom is a percentage of the container’s total memory that can be excluded from the memory calculator’s algorithm and left for non-JVM operations. This defaults to 0.
The below table lists the component parts of the Non-Heap value, the equivalent JVM flags, and their defaults. Where one exists, the JVM default value is used.
|Memory Region||JVM Flag||Default|
||10MB (JVM Default)|
||Automatically calculated based on class count|
|Reserved Code Cache||
||240MB (JVM Default)|
||1M * 250 (JVM Default Thread Stack Size * Default Optimum Thread Count for Tomcat)|
The outputs of the tool are the above JVM flags and their calculated values.
The remaining memory left after totalling these values is assigned to the
-Xmx flag as Heap. All flags and values are then appended to
JAVA_TOOL_OPTIONS when the application image is run.
It is not recommended to set the Heap memory value directly using the
The non-heap value calculated by the tool remains fixed for a constant application.
-Xmx directly could either:
Adjusting container memory limits
Decreasing the container memory limit will result in a reduced heap (
Similarly, increasing container memory limit beyond a known application’s non-heap (fixed) size will assign all of the increased value to Heap (
It is possible to override the calculated or default values specified above in the non-heap table, however the runtime consequences of adjusting these values should be considered. For more information on how to configure these explicitly, see the How-To section Configure The JVM at Runtime.
The Paketo Java buildpack supports multiple application servers. Each application server has different capabilities and configuration options. The following are a list of supported application servers and links to reference documentation for each one.
|Application Server||Buildpack Documentation||Server Documentation|
If the application uses Spring Boot the Spring Boot Buildpack will enhance the resulting image by adding additional metadata to the image config, applying Boot-specific performance optimizations, and enabling runtime auto-configuration.
The Spring Boot Buildpack adds the following additional image labels:
org.opencontainers.image.title- set to the value of
org.opencontainers.image.version- set to the values of
org.springframework.boot.version- set to the value of
org.springframework.cloud.dataflow.spring-configuration-metadata.json- containing [configuration metadata][spring boot configuration metadata].
dataflow-configuration-metadata.properties, if present.
In addition, the buildpack will add an entry with name
dependencies to the Bill-of-Materials listing the application dependencies.
The Spring Boot Buildpack can apply domain-specific knowledge to optimize the performance of Spring Boot applications. For example, if the buildpack detects that the application is a reactive web application the thread count will be reduced to
50 from a default of
The following component buildpacks compose the Java Buildpack. Buildpacks are listed in the order they are executed.
|Paketo CA Certificates Buildpack||Optional||Adds CA certificates to the system truststore at build and runtime.|
|Paketo BellSoft Liberica Buildpack||Required||Provides the JDK and/or JRE.|
|Paketo Syft||Optional||Provides the Syft CLI which can be used to generate SBOM information.|
|Paketo Leiningen Buildpack||Optional||Builds Leiningen-based applications from source.|
|Paketo Clojure Tools Buildpack||Optional||Builds Clojure applications from source.|
|Paketo Gradle Buildpack||Optional||Builds Gradle-based applications from source.|
|Paketo Maven Buildpack||Optional||Builds Maven-based applications from source.|
|Paketo SBT Buildpack||Optional||Builds SBT-based applications from source.|
|Paketo Watchexec Buildpack||Optional||Contributes the
|Paketo Executable JAR Buildpack||Optional||Contributes a process Type that launches an executable JAR.|
|Paketo Apache Tomcat Buildpack||Optional||Contributes Apache Tomcat and a process type that launches a WAR with Tomcat.|
|Paketo Apache Tomee Buildpack||Optional||Contributes Apache Tomee and a process type that launches a WAR with Tomee.|
|Paketo Liberty Buildpack||Optional||Contributes Open Liberty and a process type that launches a WAR with Open Liberty.|
|Paketo DistZip Buildpack||Optional||Contributes a process type that launches a DistZip-style application.|
|Paketo Spring Boot Buildpack||Optional||Contributes configuration and metadata to Spring Boot applications.|
|Paketo Procfile Buildpack||Optional||Allows the application to define or redefine process types with a [Procfile][procfiles]|
|Paketo JAttach||Optional||Provides the JAttach binary to send commands to a remote JVM via Dynamic Attach mechanism|
|Paketo Azure Application Insights Buildpack||Optional||Contributes the Application Insights Agent and configures it to connect to the service.|
|Paketo Google Stackdriver Buildpack||Optional||Contributes Stackdriver agents and configures them to connect to the service.|
|Paketo Datadog Buildpack||Optional||Contributes Datadog trace agent and configures it to connect to the service.|
|Paketo Java Memory Assistant Buildpack||Optional||Contributes and configures the SAP Java Memory Assistant (JMA) Agent for Java applications.|
|Paketo Encrypt At Rest Buildpack||Optional||Encrypts an application layer and contributes a profile script that decrypts it at launch time.|
|Paketo Environment Variables Buildpack||Optional||Contributes arbitrary user-provided environment variables to the image.|
|Paketo Image Labels Buildpack||Optional||Contributes OCI-specific and arbitrary user-provided labels to the image.|
Last modified: September 28, 2023