This documentation explains how to use the Paketo Ruby Buildpack to build applications for several common use-cases. For more in-depth description of the buildpack’s behavior and configuration see the Paketo Ruby Buildpack Reference documentation.
You can quickly build a sample Ruby app into a runnable OCI image on your local machine with Paketo buildpacks.
Prerequisites
Clone the Paketo samples and navigate to a Ruby sample app.
git clone https://github.com/paketo-buildpacks/samples cd samples/ruby/puma
Use the pack CLI with the Paketo Ruby Buildpack to build the sample app.
pack build my-app --buildpack paketo-buildpacks/ruby \ --builder paketobuildpacks/builder-jammy-base
Run the app using instructions found in its README.
Note: Though the example above uses the Paketo Base Builder, this buildpack is also compatible with the Paketo Full Builder.
The Paketo Ruby Buildpack will attempt to automatically detect the correct
version of Ruby to install based on the default version in the
buildpack.toml file. It is possible to override this version by
setting the BP_MRI_VERSION environment variable at build time, or via a
Gemfile in the app source.
The version can be set to any valid semver version or version constraint (e.g.
2.7.4, 2.7.*). For the versions available in the buildpack, see the
buildpack’s releases page. Specifying a version of Ruby is not
required. In the case that it is not specified, the buildpack will provide the
default version, which can be seen in the buildpack.toml file.
The buildpack prioritizes the versions specified in
each possible configuration location with the following precedence, from
highest to lowest: BP_MRI_VERSION, Gemfile.
When building with the pack CLI, set BP_MRI_VERSION at build time with the --env flag.
pack build my-app --buildpack paketo-buildpacks/ruby \ --env BP_MRI_VERSION="2.7.1"
project.toml
When building with the pack CLI, create a project.toml file
in your app directory that sets BP_MRI_VERSION at build time.
# project.toml [ _ ] schema-version = "0.2" [[ io.buildpacks.build.env ]] name="BP_MRI_VERSION" value="2.7.1"
The pack CLI will automatically detect the project file at build time.
When a Gemfile is present, include a version declaration line.
source 'https://rubygems.org' ruby '~> 2.7.1'
buildpack.yml
Please note that setting the Ruby version through a buildpack.yml file will be
deprecated in MRI Buildpack v1.0.0. To migrate from using buildpack.yml please
set the $BP_MRI_VERSION environment variable.
The Paketo Ruby Buildpack will also attempt to automatically detect the correct
version of Bundler to use based on the default version in the
buildpack.toml file. It is possible to override this version
by setting the BP_BUNDLER_VERSION environment variable at build time, or via
a Gemfile.lock created during dependency vendoring.
The version can be set to any valid semver version or version constraint (e.g.
2.2.29, 2.2.*). For the versions available in the buildpack, see the
buildpack’s releases page. Specifying a version of Ruby is
not required. In the case that it is not specified, the buildpack will provide
the default version, which can be seen in the buildpack.toml file.
The buildpack prioritizes the versions specified in each possible configuration
location with the following precedence, from highest to lowest:
BP_BUNDLER_VERSION, Gemfile.lock.
When building with the pack CLI, set BP_BUNDLER_VERSION at build time with the --env flag.
pack build my-app --buildpack paketo-buildpacks/ruby \ --env BP_BUNDLER_VERSION="2.1.4"
project.toml
When building with the pack CLI, create a project.toml file
in your app directory that sets BP_BUNDLER_VERSION at build time.
# project.toml [ _ ] schema-version = "0.2" [[ io.buildpacks.build.env ]] name="BP_BUNDLER_VERSION" value="2.1.4"
The pack CLI will automatically detect the project file at build time.
When configuring your app, run bundle install on the source code to configure
the buildpack to use the version of Bundler that you bundled with. This will
result in a Gemfile.lock file that includes a Bundler version declaration line.
BUNDLED WITH 2.1.4
buildpack.yml
Please note that setting the Bundler version through a buildpack.yml file
will be deprecated in Bundler Buildpack v1.0.0.
In order to build apps that contain vendored gems with the Paketo Ruby
Buildpack, your app will need to have .gem files located in the
cache_path.
Running the bundle package command on your app source code will
copy the required gems into the cache location, typically vendor/cache. This
will indicate to the buildpack to use gems in the cache over those on the
RubyGems index. Check out the Ruby reference documentation for more information about how this works.
To vendor gems in a non-default location, put all .gem files into the
directory inside app source code, such as custom_dir/custom_cache. In order
to tell the buildpack where to look for the gems, create a .bundle/config
file and set the BUNDLE_CACHE_PATH.
--- BUNDLE_CACHE_PATH: "custom_dir/custom_cache"
The Ruby Buildpack can build images that run a rake task
at launch time. Simply include a valid Rakefile in your app source
code. The buildpack will build an image that runs the default rake task
at launch time.
See this Paketo sample app for a working example.
To configure the app image to run a rake task called non_default on launch,
use a Procfile with the
start command set as the web process.
web: bundle exec rake non_default
Alternatively, start the app container with the rake task (instead of its default start
command), by setting --entrypoint launcher when running the container, and
add the desired rake start command at the end.
docker run --entrypoint launcher my-rake-app bundle exec rake non_default
The Paketo Ruby Buildpack has support for several common web servers and will configure the app image accordingly. Check out the Ruby reference documentation for more information about the supported web servers.
To enable your app to run with a given webserver, include its gem in your app’s
Gemfile.
For example, to use Rackup, include in your Gemfile:
gem 'rack'
If you are building a Rails (version >= 5.0) app that needs asset compilation, you can build it with the Paketo Ruby Buildpack.
To use this feature:
app/assets directory in your app source coderails gem to your GemfileDEBUG logging
Users of the Ruby buildpack can access extra debug logs during the image build process by setting the BP_LOG_LEVEL
environment variable to DEBUG at build time. Additional debug logs will
appear in build logs if the relevant buildpacks have debug log lines.
pack build my-app --buildpack paketo-buildpacks/ruby \ --env BP_LOG_LEVEL=DEBUG
The Ruby buildpack includes support for the software bill of materials (SBOM). Check out the SBOM how-to documentation for details on how to access the SBOM supplied by the buildpacks.
SBOMs will be generated for applications which leverage Bundler.
Last modified: April 3, 2024