Using Bundler

To use, install bundler:

$ gem install bundler

Create a file named Gemfile in the root of your app specifying what gems are required to run it:

source "https://rubygems.org"
gem 'sinatra', '1.0'

This file should be added to the git repository since it is part of the app. You should also add the .bundle directory to your .gitignore file. Once you have added the Gemfile, it makes it easy for other developers to get their environment ready to run the app:

$ bundle install -j4

This ensures that all gems specified in Gemfile, together with their dependencies, are available for your application. Running bundle install also generates a Gemfile.lock file, which should be added to your git repository. Gemfile.lock ensures that your deployed versions of gems on Heroku match the version installed locally on your development machine. The flag -j4 will use 4 parallel jobs to install all of your dependencies. This feature was introduced in bundler 1.5.0

If the platforms section of your Gemfile contains Windows entries, such as mswin or mingw, then the Gemfile.lock file will be ignored.

Heroku also uses that file to resolve and install your application dependencies automatically. All you need to do is to push it:

Specifying gems and groups

The recommended use of gem bundler is to bundle absolutely every gem your app depends upon. This includes your framework (Rails, Sinatra, etc) and your database connectors.

Bundling Rails and other dependencies does increase your slug size by a few megabytes. Increased slug size is a worthwhile tradeoff for vastly simplified dependency management, as well as the flexibility of being able to use any version of Rails you wish.

To specify groups of gems to not to be installed, you can use the BUNDLE_WITHOUT config var.

$ heroku config:set BUNDLE_WITHOUT="development:test"

Frameworks

Using Bundler with Rails 3

Rails 3 is built on top of Bundler. That means there is no setup needed, all gems specified on the Gemfile are ready for use on your app.