This documentation explains how to use the Tanzu Ruby Buildpack to build applications for several common use-cases.
The Ruby Buildpack supports several versions of MRI (Matz's Ruby Interpreter), 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.
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 buildpack to vendor your dependencies using bundle install.
This section demonstrates building the Paketo Ruby Passenger Server sample app on different platforms.
workload.yaml.---
apiVersion: carto.run/v1alpha1
kind: Workload
metadata:
labels:
app.kubernetes.io/part-of: ruby-sample
apps.tanzu.vmware.com/has-tests: "true"
apps.tanzu.vmware.com/workload-type: web
name: ruby-sample
spec:
params:
- name: ports
value:
- port: 80
containerPort: 8000
name: http
source:
git:
ref:
branch: main
url: https://github.com/paketo-buildpacks/samples
subPath: ruby/passenger
where metadata.name is the application name the workload is a part of, and spec.source.git points to the remote source code.
my-apps namespace by running:tanzu apps workload apply --file workload.yaml --namespace my-apps
3. You're done with build! You can view the result with:
tanzu apps workload get ruby-sample --namespace my-apps
### <a id="how-to-use-in-tbs"></a> How to use in TBS
The Ruby buildpack is available in both the `full` and `lite` descriptors
of TBS. Use `kp image create` to create an image resource. For more details,
see [Build Service
Documentation](https://docs.vmware.com/en/Tanzu-Build-Service/1.6/vmware-tanzu-build-service/GUID-managing-images.html#image-resources)
### <a id="how-to-use-with-pack"></a> How to use with `pack` CLI
The [pack CLI](https://github.com/buildpacks/pack) can be used to build your
application image.
1. From the app directory, build the image with `pack`:
pack build ruby-sample --buildpack gcr.io/tanzu-buildpacks/ruby
2. Once the build has succeeded, run the image:
docker run --interactive --tty --env PORT=8080 --publish 8080:8080 ruby-sample
3. View the running application by visiting `http://localhost:8080` in a browser.
## <a id="override-mri"></a> Override the Detected Ruby Version
The Ruby Buildpack will attempt to automatically detect the correct version of
Ruby (Matz's Ruby Interpreter or MRI) to install based on the default version
set by the buildpack. 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 [release notes](GUID-ruby-release-notes.html). Specifying a version
of Ruby is not required. In the case that it is not specified, the buildpack
will provide the default version.
The buildpack prioritizes the versions specified in each possible configuration
location with the following precedence, from highest to lowest:
* `BP_MRI_VERSION`
* Gemfile
### <a id="project-toml-mri"></a> Via project.toml
```toml
[ build ]
[[ build.env ]]
name="BP_MRI_VERSION"
value="2.7.1"
pack)pack build my-app --buildpack gcr.io/tanzu-buildpacks/ruby --env BP_MRI_VERSION="2.7.1"
When a Gemfile is present, include a version declaration line.
source 'https://rubygems.org'
ruby '~> 2.7.1'
buildpack.ymlPlease note that setting the Ruby version through a buildpack.yml file will be deprecated in the next major release of the Ruby buildpack (v3.0.0). To migrate from using buildpack.yml please set the $BP_MRI_VERSION environment variable.
The Ruby Buildpack will also attempt to automatically detect the correct version of Bundler to use based on the default version set by the buildpack. 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 release notes. Specifying a version of Bundler is not required. In the case that it is not specified, the buildpack will provide the default version.
The buildpack prioritizes the versions specified in each possible configuration location with the following precedence, from highest to lowest:
BP_BUNDLER_VERSIONGemfile.lock[ build ]
[[ build.env ]]
name="BP_BUNDLER_VERSION"
value="2.1.4"
pack)pack build my-app --buildpack gcr.io/tanzu-buildpacks/ruby --env BP_BUNDLER_VERSION="2.1.4"
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.ymlPlease note that setting the Bundler version through a buildpack.yml file will be deprecated in the next major release of the Ruby Buildpack (v3.0.0). To migrate from using buildpack.yml please set the $BP_BUNDLER_VERSION environment variable.
In order to build apps that contain vendored gems with the 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. 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.
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.
The Ruby Buildpack supports several common web servers and will configure the app image accordingly. The Ruby Buildpack supports a number of webservers 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.
The following web servers are supported:
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 Ruby Buildpack.
To use this feature:
app/assets directory in your app source coderails gem to your GemfileThe buildpack runs bundle exec rails assets:precompile for the app, and works with any of the supported Ruby webservers listed above. The Ruby Buildpack leverages the Tanzu Node Engine Buildpack to support asset compilation.
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 SBOM format. This Paketo-specific SBOM format does not include information about the application dependencies.
Check out the SBOM documentation for details on how to access the SBOM supplied by the buildpacks.
SBOMs will be generated for applications which leverage bundler.
DEBUG loggingUsers 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.
[build]
[[build.env]]
name = 'BP_LOG_LEVEL'
value = 'DEBUG'
pack)pack build my-app --buildpack gcr.io/tanzu-buildpacks/ruby \
--env BP_LOG_LEVEL=DEBUG
