Deep-dive on the Next Gen Platform. Join the Webinar!

Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
Hide categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Node.js Behavior in Heroku
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Language Support
  • Ruby
  • Ruby Behavior in Heroku
  • Ruby Behavior in Heroku

Ruby Behavior in Heroku

Last updated February 12, 2025

Table of Contents

  • Auto-Detection
  • Config Vars
  • Installed Bundler Versions
  • Available Process Types
  • Ruby Apps Build Behavior
  • Specific Ruby Application Behavior
  • Additional Reading

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:

  • Gemfile for a Ruby application
  • config.ru for a Rack application
  • config/environment.rb for a Rails 2 application
  • config/application.rb containing the string Rails::Application for a Rails 3 application

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:

  • Ruby Application Behavior on Heroku
  • Rack Application Behavior on Heroku
  • Rails Application Behavior on Heroku

Additional Reading

  • Heroku Ruby Support
  • Specifying a Ruby Version
  • Working with Ruby category
  • Ruby on Heroku Behavior category

Keep reading

  • Ruby Behavior in Heroku

Feedback

Log in to submit feedback.

Ruby Default Web Server Ruby Database Auto-Provisioning

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices