Ruby Behavior in Heroku

Last updated February 12, 2025

The Heroku Platform and Ruby buildpack has the following behavior for any type of Ruby application deployed. For more formal details, view the classic Ruby buildpack or the Ruby Cloud Native Buildpack’s specification.

For behavior related to specific types of Ruby apps, see our articles about pure Ruby, Rails, and Rack-based apps.

Auto-Detection

Ruby applications on Heroku must have a Gemfile.lock in the root directory so that we can auto-detect the correct buildpack to use. Even if an application has no gem dependencies it must include an empty Gemfile to document that your app has no gem dependencies.

Auto-Detection with Classic Buildpacks

With classic buildpacks, We take articular actions depending on the type of application deployed, as determined by the presence of the following files:

Config Vars

We set the environment variables listed in Ruby Application Behavior on all Ruby apps.

In addition, we set additional variables for Rack and Rails apps as listed in Rack Application Behavior and Rails Application Behavior

Installed Bundler Versions

The Heroku platform uses a specific set of libraries for managing and running Ruby applications. The Ruby buildpack installs a version of Bundler based on the major and minor version listed in the Gemfile.lock under the BUNDLED WITH key:

BUNDLED WITH 1.x installs bundler 1.17.3 BUNDLED WITH 2.0.x to 2.3.x installs bundler 2.3.25 BUNDLED WITH 2.4.x installs bundler 2.4.22 BUNDLED WITH 2.5.x installs bundler 2.5.6

If your Gemfile.lock doesn’t include the BUNDLED WITH key, we use a default version.

For more information on why we only support specific versions, see Bundler Version. For more information on available settings, see Bundler configuration.

Available Process Types

The following two process types are always available:

rake: bundle exec rake
console: bundle exec irb

Process Types with Cloud Native Buildpack Apps

Given an application with the railties gem:

  • We default the web process to bin/rails server while specifying -p $PORT and -e $RAILS_ENV". Use the Procfile to override this default.

If we can’t find the railties gem, but the rack gem is present and a config.ru file exists on root:

  • We default the web process to rackup while specifying -p $PORT and -h 0.0.0.0. Use the Procfile to override this default.

Ruby Apps Build Behavior

Builds With Classic Buildpacks

When an application deploys, the build phase configures the underlying Rack or Rails application to use the provisioned database if a config directory and a RAILS_ENV or RACK_ENV environment variable exist.

Before ActiveRecord 4.1, which Rails 4.1+ uses, a database.yml file is created. An existing database.yml file gets replaced. The database.yml file is created as Ruby code that dynamically creates its output by parsing the DATABASE_URL environment variable.

In ActiveRecord 4.1+, DATABASE_URL support is baked in. For more information, see configuring database connections and the pull request that added DATABASE_URL support

At the end of the build, we check the application for potentially problematic application configuration via the rails runner interface.

JRuby

For JRuby, you can customize the options passed to the JVM during the build by setting the config var JRUBY_BUILD_OPTS. A common value is --dev, which optimizes the runtime for short processes like those executed by Bundler and Rake.

Builds with Cloud Native Buildpacks

If the application specifies a rake assets:precompile task, it gets executed. The builder detects the task by running rake -P with the specified environment variables. If the application specifies the rake assets:precompile:clean task, it is invoked after a successful assets:precompile call.

Some applications and libraries can use monkey-patching or Rake::Task#enhance calls to modify this assets:precompile task. For example, this technique was used to call yarn install in older versions of Rails. We don’t manually call any of these setup or helper tasks. We expect rake assets:precompile to invoke whatever is necessary for your application to build assets. You can also configure your application to install them ahead of time via another buildpack, such as the heroku/nodejs buildpack.

Specific Ruby Application Behavior

For behavior related to specific types of Ruby apps, see the following articles:

Additional Reading