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

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

Examples

• Embedded web server
• Grails
• Groovy
• Java Main
• Play Framework
• Servlet

Configuration and Extension

Configurable framework and JRE settings are overridden through component-specific JBP_CONFIG_* environment variables (for example, JBP_CONFIG_OPEN_JDK_JRE and JBP_CONFIG_DEBUG). Consult each component's documentation for its exact variable name and supported fields. The value must be valid inline YAML, referred to as "flow style" in the YAML spec ([Wikipedia][] has a good description of this syntax).

Note: The Ruby buildpack's config/*.yml file-based configuration is not used by this buildpack. All configuration is done through environment variables as described below.

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.+ }}"}'

1. 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\" }"}'

1. 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 } }'

1. 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" }'

1. 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" }'

1. 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'

1. 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 }'

1. 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_ 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.

GA Status

v5.1.0 is the first generally available (GA) release of the Go-based Java Buildpack.

This release is declared GA in accordance with [RFC-0050][] and supersedes the experimental Go buildpack releases in the 5.0.x line. The Ruby-based buildpack (4.x) is no longer receiving feature updates; operators are encouraged to migrate to v5.1.0 or later.

[RFC-0050]: https://github.com/cloudfoundry/community/blob/main/toc/rfc/rfc-0050-java-buildpack-migration-to-golang.md

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

Quick Status Summary (as of September 25, 2026):

• ✅ All 7 supported application types implemented (100%; 6 registered container implementations — Ratpack is detected as a DistZip application type, not a separate container)
• ✅ 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

Additional Documentation

• Design
• Security
• v5.1.0 Release Notes (draft)
• Standard Containers

• Standard Frameworks

• Standard JREs (Included in Manifest)

• BYOL JREs (Require Custom Manifest - see Custom JRE Usage)

• Debugging the Buildpack
• Buildpack Modes
• Related Projects

Building Packages

Requirements:

• Go 1.21 or higher
• Git

Online Package

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

Offline Package

$ ./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:

| Invocation | Output filename | |---|---| | --cached | java_buildpack-cached-cflinuxfs4-v.zip | | --cached --profile minimal | java_buildpack-cached-minimal-cflinuxfs4-v.zip | | --cached --exclude newrelic | java_buildpack-cached-custom-cflinuxfs4-v.zip | | --cached --profile minimal --include jprofiler-profiler | java_buildpack-cached-minimal+custom-cflinuxfs4-v.zip |

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

$ ./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)

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

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

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

Contributing

License

[Apache License]: http://www.apache.org/licenses/LICENSE-2.0 [Cloud Foundry]: http://www.cloudfoundry.org [contributor guidelines]: CONTRIBUTING.md [disables remote_downloads]: docs/extending-caches.md#configuration [Environment Variables]: http://docs.cloudfoundry.org/devguide/deploy-apps/manifest.html#env-block [GitHub's forking functionality]: https://help.github.com/articles/fork-a-repo [Grails]: https://grails.apache.org/ [Groovy]: https://groovy-lang.org/ [Play Framework]: http://www.playframework.com [pull request]: https://help.github.com/articles/using-pull-requests [Pull requests]: http://help.github.com/send-pull-requests [Running Cloud Foundry locally]: https://github.com/cloudfoundry/cf-deployment/tree/master/iaas-support/bosh-lite [Spring Boot]: http://projects.spring.io/spring-boot/ [Wikipedia]: https://en.wikipedia.org/wiki/YAML#Basic_components_of_YAML