docs community resources blog github

Ruby Buildpack Reference

This reference documentation offers an in-depth description of the behavior and configuration options of the Paketo Ruby Buildpack. For explanations of how to use the buildpack for several common use-cases, see the Paketo Ruby Buildpack How To documentation.

Supported Dependencies

The Ruby Paketo Buildpack supports several versions of MRI, Bundler, and common Ruby webservers and task runners. For more details on the specific versions supported in a given buildpack version, see the release notes.

Package Management

The Ruby Buildpack uses Bundler to install and manage the gems needed to run your application. Including a Gemfile in your app source code instructs the bundle-install buildpack to vendor your dependencies using bundle install.

Webservers & Task Runners

The Ruby Buildpack supports a number of webservers and task runners that are useful for running Ruby applications. If your application uses one of these tools, it will be automatically detected and a start command for your application will be assigned when building your application container.


Task Runners

Rails Asset Pipeline

The Paketo Rails Assets Buildpack is a component buildpack included in the Ruby Buildpack. It supports Rails apps (Rails version >= 5.0) that need asset precompilation.

The buildpack runs bundle exec rails assets:precompile for the app, and works with any of the supported Ruby webservers listed above. The Paketo Ruby Buildpack pulls in this buildpack, as well as the Paketo Node Engine Buildpack to support asset compilation.

Reproducible Builds and Limitations

The Paketo Ruby Buildpack supports reproducible builds for most use cases, meaning application images produced with identical inputs will produce images with the same digests.

Builds that leverage the Paketo Rails Assets Buildpack are unfortunately NOT reproducible, due to limitations in the Rails implementation related to the usage of the sprockets gem. There is no known workaround for this limitation, unless the Rails project itself undergoes changes to enable reproducible builds.

Vendored Gem Behavior

Per the Ruby How To Guide, the Paketo Ruby Buildpack supports building apps with vendored gems. Behind the scenes, the presence of the cache path in the app source code indicates to the buildpack to run bundle install with the addition of the --local flag to prefer the use of local gems.

Buildpack-Set Environment Variables

The Ruby CNB sets a few environment variables during the build and launch phases of the app lifecycle. The sections below describe each environment variable and its impact on your app.


  • Set by: mri, bundler
  • Phases: build and launch
  • Value: location of the directory gems will be installed for each respective dependency


  • Set by: bundle-install
  • Phases: build and launch
  • Value: location where all gems in your bundle will be located

Software Bill of Materials

The Ruby buildpack supports the full software bill of materials (SBOM) in Syft, CycloneDX, and SPDX formats. The Ruby buildpack also includes limited support for the Paketo-specific SBOM format. This Paketo-specific SBOM format does not include information about the application dependencies.

SBOMs will be generated for applications which leverage Bundler.

Check out the Access the Software Bill of Materials guide for more information about how to retrieve the SBOM for your Ruby app image.


Last modified: June 18, 2024