cloudfoundry/java-buildpack

Cloud Foundry Java Buildpack

The java-buildpack is a Cloud Foundry buildpack for running JVM-based applications. It is designed to run many JVM-based applications (Grails, Groovy, Java Main, Play Framework, Spring Boot, and Servlet) with no additional configuration, but supports configuration of the standard components, and extension to add custom components.

Usage

To use this buildpack specify the URI of the repository when pushing an application to Cloud Foundry:

$ cf push <APP-NAME> -p <ARTIFACT> -b https://github.com/cloudfoundry/java-buildpack.git

Examples

The following are very simple examples for deploying the artifact types that we support.

• Embedded web server
• Grails
• Groovy
• Java Main
• Play Framework
• Servlet
• Spring Boot CLI

Configuration and Extension

The buildpack default configuration can be overridden with an environment variable matching the configuration file you wish to override minus the .yml extension. It is not possible to add new configuration properties and properties with nil or empty values will be ignored by the buildpack (in this case you will have to extend the buildpack, see below). The value of the variable should be valid inline yaml, referred to as "flow style" in the yaml spec (Wikipedia has a good description of this yaml syntax).

There are two levels of overrides: operator and application developer.

• If you are an operator that wishes to override configuration across a foundation, you may do this by setting environment variable group entries that begin with a prefix of JBP_DEFAULT.
• If you are an application developer that wishes to override configuration for an individual application, you may do this by setting environment variables that begin with a prefix of JBP_CONFIG.

Here are some examples:

Operator

1. To change the default version of Java to 11 across all applications on a foundation.

$ cf set-staging-environment-variable-group '{"JBP_DEFAULT_OPEN_JDK_JRE":"{jre: {version: 11.+ }}"}'

2. To change the default repository root across all applications on a foundation. Be careful to ensure that your JSON is properly escaped.

$ cf set-staging-environment-variable-group '{"JBP_DEFAULT_REPOSITORY": "{default_repository_root: \"http://repo.example.io\" }"}'

3. DEPRECATED: To change the default JVM vendor across all applications on a foundation, use JRE-specific environment variables instead. JBP_CONFIG_COMPONENTS for JRE selection is no longer supported in the Go buildpack.

# Use this instead
$ cf set-staging-environment-variable-group '{"JBP_DEFAULT_ZULU_JRE":"{jre: {version: 17.+ }}"}'

Application Developer

1. To change the default version of Java to 11 and adjust the memory heuristics then apply this environment variable to the application.

$ cf set-env my-application JBP_CONFIG_OPEN_JDK_JRE '{ jre: { version: 11.+ }, memory_calculator: { stack_threads: 25 } }'

2. If the key or value contains a special character such as : it should be escaped with double quotes. For example, to change the default repository path for the buildpack.

$ cf set-env my-application JBP_CONFIG_REPOSITORY '{ default_repository_root: "http://repo.example.io" }'

3. If the key or value contains an environment variable that you want to bind at runtime you need to escape it from your shell. For example, to add command line arguments containing an environment variable to a Java Main application.

$ cf set-env my-application JBP_CONFIG_JAVA_MAIN '{ arguments: "--server.port=9090 --foo=bar" }'

4. An example of configuration is to specify a javaagent that is packaged within an application.

$ cf set-env my-application JAVA_OPTS '-javaagent:app/META-INF/myagent.jar -Dmyagent.config_file=app/META-INF/my_agent.conf'

5. Environment variable can also be specified in the applications manifest file. For example, to specify an environment variable in an applications manifest file that disables Auto-reconfiguration.

env:
  JBP_CONFIG_SPRING_AUTO_RECONFIGURATION: '{ enabled: false }'

6. This final example shows how to change the version of Tomcat that is used by the buildpack with an environment variable specified in the applications manifest file.

env:
  JBP_CONFIG_TOMCAT: '{ tomcat: { version: 8.0.+ } }'

See the Environment Variables documentation for more information.

JRE Selection

Important: The Go buildpack does NOT support JBP_CONFIG_COMPONENTS for JRE selection (this differs from the Ruby buildpack). This environment variable is deprecated in favor of using JRE-specific configuration variables.

To select a different JRE, use the appropriate JBP_CONFIG_<JRE_NAME> variable:

# Switch to SapMachine JRE
$ cf set-env my-app JBP_CONFIG_SAP_MACHINE_JRE '{ jre: { version: 17.+ }}'

# Switch to Zulu JRE
$ cf set-env my-app JBP_CONFIG_ZULU_JRE '{ jre: { version: 21.+ }}'

# For BYOL JREs (Oracle, GraalVM, IBM, Zing), you must first add them to manifest.yml
# See https://github.com/cloudfoundry/java-buildpack/blob/main/docs/custom-jre-usage.md

The buildpack will automatically detect and use the configured JRE without requiring JBP_CONFIG_COMPONENTS.

See the Environment Variables documentation for more information.

To learn how to configure various properties of the buildpack, follow the "Configuration" links below.

The buildpack supports extension through the use of Git repository forking. The easiest way to accomplish this is to use GitHub's forking functionality to create a copy of this repository. Make the required extension changes in the copy of the repository. Then specify the URL of the new repository when pushing Cloud Foundry applications. If the modifications are generally applicable to the Cloud Foundry community, please submit a pull request with the changes. More information on extending the buildpack is available here.

Ruby vs Go Migration Status

This Go-based buildpack is a migration from the original Ruby-based Cloud Foundry Java Buildpack. For comprehensive information about the migration status, component parity, and architectural differences:

• Ruby vs Go Buildpack Comparison - Technical deep-dive into how dependency extraction differs between Ruby and Go implementations

⚠️ Important Migration Note: The Go buildpack does NOT support the Ruby buildpack's repository_root configuration approach for custom JREs (via JBP_CONFIG_* environment variables). Custom JREs now require forking the buildpack and modifying manifest.yml. See Custom JRE Usage for details.

Quick Status Summary (as of December 16, 2025):

• ✅ All 8 container types implemented (100%)
• ✅ All 7 JRE providers implemented (3 in manifest + 4 BYOL via custom manifest)
• ✅ 37 of 40 frameworks implemented (92.5%)
• ✅ All integration tests passing
• ⚠️ Only 3 missing frameworks are niche/deprecated (affecting <2% of applications)
• 📝 BYOL JREs (GraalVM, IBM, Oracle, Zing) require custom manifest - see Custom JRE Usage

For historical analysis documents from development sessions, see docs/archive/.

Additional Documentation

• Design
• Security
• Standard Containers
  • Dist ZIP
  • Groovy (Configuration)
  • Java Main (Configuration)
  • Play Framework
  • Ratpack
  • Spring Boot
  • Spring Boot CLI (Configuration)
  • Tomcat (Configuration)
• Standard Frameworks
  • AppDynamics Agent (Configuration)
  • AspectJ Weaver Agent (Configuration)
  • Azure Application Insights Agent (Configuration)
  • Checkmarx IAST Agent (Configuration)
  • Client Certificate Mapper (Configuration)
  • Container Customizer (Configuration)
  • Container Security Provider (Configuration)
  • Contrast Security Agent (Configuration)
  • DataDog (Configuration
  • Debug (Configuration)
  • Elastic APM Agent (Configuration)
  • Dynatrace SaaS/Managed OneAgent (Configuration)
  • Google Stackdriver Profiler (Configuration)
  • Introscope Agent (Configuration)
  • JaCoCo Agent (Configuration)
  • Java CfEnv (Configuration)
  • Java Memory Assistant (Configuration)
  • Java Options (Configuration)
  • JProfiler Profiler (Configuration)
  • JRebel Agent (Configuration)
  • JMX (Configuration)
  • Luna Security Provider (Configuration)
  • MariaDB JDBC (Configuration) (also supports MySQL)
  • Multiple Buildpack
  • Metric Writer (Configuration)
  • New Relic Agent (Configuration)
  • PostgreSQL JDBC (Configuration)
  • ProtectApp Security Provider (Configuration)
  • Riverbed AppInternals Agent (Configuration)
  • Sealights Agent (Configuration)
  • Seeker Security Provider (Configuration)
  • Splunk Observability Cloud (Configuration)
  • Spring Auto Reconfiguration (Configuration)
  • Spring Insight
  • SkyWalking Agent (Configuration)
  • YourKit Profiler (Configuration)
• Standard JREs (Included in Manifest)
  • OpenJDK (Configuration) - Default
  • Azul Zulu (Configuration)
  • SapMachine (Configuration)
• BYOL JREs (Require Custom Manifest - see Custom JRE Usage)
  • Azul Platform Prime (Zing) (Configuration)
  • GraalVM (Configuration)
  • IBM Semeru (Configuration)
  • Oracle (Configuration)
• Debugging the Buildpack
• Buildpack Modes
• Related Projects
  • Java Buildpack Dependency Builder
  • Java Buildpack Memory Calculator
  • Java Test Applications
  • Java Buildpack System Tests
  • jvmkill

Building Packages

The buildpack can be packaged up so that it can be uploaded to Cloud Foundry using the cf create-buildpack and cf update-buildpack commands. The Go buildpack uses the buildpack-packager tool to create packages.

Requirements:

• Go 1.21 or higher
• Git

Note that this process is not currently supported on Windows. It is possible it will work, but it is not tested.

Online Package

The online package is a version of the buildpack that is as minimal as possible and is configured to connect to the network for all dependencies. This package is about 1-2 MB in size. To create the online package, run:

$ ./scripts/package.sh
...
Building buildpack (version: 0.0.0, stack: cflinuxfs4, cached: false, output: build/buildpack.zip)

Offline Package

The offline package is a version of the buildpack designed to run without access to a network. It packages all dependencies listed in manifest.yml and includes them in the buildpack archive. To create the offline package, use the --cached flag:

$ ./scripts/package.sh --cached
...
Building buildpack (version: 0.0.0, stack: cflinuxfs4, cached: true, output: build/buildpack.zip)

The offline package will be significantly larger (1.0-1.2 GB depending on cached dependencies) as it includes all JRE versions and framework agents specified in manifest.yml.

Selective Dependency Packaging

For air-gapped environments or security-conscious deployments, you can build a smaller offline package that contains only a named subset of dependencies using packaging profiles or explicit exclusions.

Using a profile (defined in manifest.yml):

# Minimal: JDKs, CF utilities, Tomcat, and common frameworks only (~28 dependencies)
$ ./scripts/package.sh --cached --profile minimal

# Standard: core + open-source APM, OTel, and JDBC drivers (~32 dependencies)
$ ./scripts/package.sh --cached --profile standard

Ad-hoc exclusions (no profile required):

# Exclude specific agents you don't have licences for
$ ./scripts/package.sh --cached --exclude jrebel,your-kit-profiler,jprofiler-profiler

Combining a profile with overrides:

# Start from standard profile but also drop jacoco
$ ./scripts/package.sh --cached --profile standard --exclude jacoco

# Start from minimal profile but add back jprofiler for triage builds
$ ./scripts/package.sh --cached --profile minimal --include jprofiler-profiler

The output zip filename reflects the profile/exclusion applied so that different variants can coexist:

Note: --profile, --exclude, and --include are only valid with --cached. Using them on an uncached build is an error. --include requires --profile to be set.

Package Versioning

To specify a version number when creating a package, use the --version flag:

$ ./scripts/package.sh --version 5.0.0
...
Building buildpack (version: 5.0.0, stack: cflinuxfs4, cached: false, output: build/buildpack.zip)

If no version is specified, the version from the VERSION file will be used (or 0.0.0 if the file doesn't exist).

Package Options

The packaging script supports the following options:

$ ./scripts/package.sh --help

package.sh --version <version> [OPTIONS]
Packages the buildpack into a .zip file.

OPTIONS
  --help               -h            prints the command usage
  --version <version>  -v <version>  specifies the version number to use when packaging the buildpack
  --cached                           cache the buildpack dependencies (default: false)
  --stack  <stack>                   specifies the stack (default: cflinuxfs4)
  --output <file>                    output file path (default: build/buildpack.zip)
  --profile <name>                   packaging profile from manifest.yml (e.g. minimal, standard)
  --exclude <dep1,dep2,...>          comma-separated dependency names to exclude (cached only)
  --include <dep1,dep2,...>          comma-separated dependency names to restore, overriding profile exclusions (cached only)

Customizing Dependencies

To customize which dependencies are included in the buildpack, edit manifest.yml:

1. Add/remove dependencies: Modify the dependencies section
2. Specify versions: Use exact versions or version wildcards (e.g., 17.x for latest Java 17)
3. Add custom JREs: For BYOL JREs (Oracle, GraalVM, IBM, Zing), add entries with your repository URIs (see Custom JRE Usage)

Example manifest entry:

dependencies:
  - name: openjdk
    version: 17.0.13
    uri: https://github.com/adoptium/temurin17-binaries/releases/download/...
    sha256: abc123...
    cf_stacks:
      - cflinuxfs4

Note: The Go buildpack does not use Ruby's config/*.yml files, bundle, or rake tasks. All dependency configuration is managed through manifest.yml.

Package Examples

# Online package with version 5.0.0
$ ./scripts/package.sh --version 5.0.0

# Offline package with version 5.0.0 (all dependencies)
$ ./scripts/package.sh --version 5.0.0 --cached

# Package for specific stack
$ ./scripts/package.sh --stack cflinuxfs4 --cached

# Custom output location
$ ./scripts/package.sh --version 5.0.0 --cached --output /tmp/my-buildpack.zip

# Offline package with minimal profile (JDKs + CF utilities only)
$ ./scripts/package.sh --version 5.0.0 --cached --profile minimal

# Offline package with standard profile (core + open-source observability)
$ ./scripts/package.sh --version 5.0.0 --cached --profile standard

# Exclude specific dependencies without a profile
$ ./scripts/package.sh --version 5.0.0 --cached --exclude jrebel,your-kit-profiler

# Minimal profile, but add back jprofiler for this specific build
$ ./scripts/package.sh --version 5.0.0 --cached --profile minimal --include jprofiler-profiler

Running Tests

To run the tests, do the following:

$ ./scripts/package.sh
$ ./scripts/unit.sh
$ BUILDPACK_FILE="$(pwd)/build/buildpack.zip" \
./scripts/integration.sh --platform docker --parallel true  --github-token MYTOKEN

For detailed guidelines about setting up and running tests please check this Testing Guide

Running Cloud Foundry locally is useful for privately testing new features.

Contributing

Pull requests are welcome; see the contributor guidelines for details.

License

This buildpack is released under version 2.0 of the Apache License.