Yehuda Katz is a member of the Ember.js, Ruby on Rails and jQuery Core Teams; he spends his daytime hours at the startup he founded, Tilde Inc.. Yehuda is co-author of best-selling jQuery in Action and Rails 3 in Action. He spends most of his time hacking on open source—his main projects, like Thor, Handlebars and Janus—or traveling the world doing evangelism work. He can be found on Twitter as @wycats and on Github.
Bundler: As Simple as What You Did Before
September 30th, 2010
One thing we hear a lot by people who start to use bundler is that the workflow is more complicated than it used to be when they first start. Here’s one (anonymized) example: “Trying out Bundler to package my gems. Still of the opinion its over-complicating a relatively simple concept, I just want to install gems.”
Bundler has a lot of advanced features, and it’s definitely possible to model fairly complex workflows. However, we designed the simple case to be extremely simple, and to usually be even less work than what you did before. The problem often comes when trying to handle a slightly off-the-path problem, and using a much more complex solution than you need to. This can make *everything* much more complicated than it needs to be.
In this post, I’ll walk through the bundler happy path, and show some design decisions we made to keep things moving as smoothly as before, but with far fewer snags and problems than the approach you were using before. I should be clear that there are probably bugs in some cases when using a number of advanced features together, and we should fix those bugs. However, they don’t reflect core design decisions of bundler.
In the Beginning
When you create a Rails application for the first time, the Rails installer creates a Gemfile for you. You’ll note that you don’t actually have to run
bundle install before starting the Rails server.
$ gem install rails Successfully installed activesupport-3.0.0 Successfully installed builder-2.1.2 Successfully installed i18n-0.4.1 Successfully installed activemodel-3.0.0 Successfully installed rack-1.2.1 Successfully installed rack-test-0.5.6 Successfully installed rack-mount-0.6.13 Successfully installed tzinfo-0.3.23 Successfully installed abstract-1.0.0 Successfully installed erubis-2.6.6 Successfully installed actionpack-3.0.0 Successfully installed arel-1.0.1 Successfully installed activerecord-3.0.0 Successfully installed activeresource-3.0.0 Successfully installed mime-types-1.16 Successfully installed polyglot-0.3.1 Successfully installed treetop-1.4.8 Successfully installed mail-22.214.171.124 Successfully installed actionmailer-3.0.0 Successfully installed thor-0.14.2 Successfully installed railties-3.0.0 Successfully installed rails-3.0.0 22 gems installed $ rails s => Booting WEBrick => Rails 3.0.0 application starting in development on http://0.0.0.0:3000 => Call with -d to detach => Ctrl-C to shutdown server [2010-09-30 12:25:51] INFO WEBrick 1.3.1 [2010-09-30 12:25:51] INFO ruby 1.9.2 (2010-08-18) [x86_64-darwin10.4.0] [2010-09-30 12:25:51] INFO WEBrick::HTTPServer#start: pid=26380 port=3000
If you take a look at your directory, you’ll see that Bundler noticed that you didn’t yet have a
Gemfile.lock, saw that you had all the gems that you needed already in your system, and created a
Gemfile.lock for you. If you didn’t have a necessary gem, the Rails server would error out. For instance, if you were missing Erubis, you’d get
Could not find RubyGem erubis (~> 2.6.6). In this case, you’d run
bundle install to install the gems.
As you can see, while bundler is providing some added features for you. If you take your application to a new development or production machine with the
Gemfile.lock, you will always use exactly the same gems. Additionally, bundler will resolve all your dependencies at once, completely eliminating the problem exemplified by this thread on the Rails core mailing list. But you didn’t have to run
bundle install or any bundle command unless you were missing some needed gems. This makes the core experience of bundler the same as “I just want to install gems”, while adding some new benefits.
When you add a gem that is already installed on your system, you just add it to the
Gemfile and start the server. Bundler will automatically pick it up and add it to the
Gemfile.lock. Here again, you don’t need to run
bundle install. To install the gem you added, you can run
bundle install or you can even just use
gem install to install the missing gems.
Once again, while bundler is handling a lot for you behind the scenes (ensuring compatibility of gems, tracking dependencies across machines), if you have all the gems that you need (and specified in your Gemfile) already installed on your system, no additional commands are required. If you don’t, a simple
bundle install will get you up to date.
After developing your application, you will probably need to deploy it. With bundler, if you are deploying your application with capistrano, you just add
require "bundler/capistrano" to your
deploy.rb. This will automatically install the gems in your
Gemfile, using deployment-friendly settings. That’s it!
Before bundler, you had two options:
- Most commonly, “make sure that all the gems I need are on the remote system”. This could involve including the
gem installin the capistrano task, or even
sshing into the remote system to install the needed gems. This solution would work, but would often leave no trail about what exactly happened. This was especially problematic for applications with a lot of dependencies, or applications with sporadic maintenance
- Using the GemInstaller gem, which allowed you to list the gems you were using, and then ran
gem installon each of the gems. Heroku used a similar approach, with a
.gemsmanifest. While this solved the problem of top-level dependencies, it did not lock in dependencies of dependencies. This caused extremely common problems with
rackand activesupport, and a long tail of other issues. One particularly egregious example is DreamHost, which directs users to use a brittle patch to Rails
In both of these cases, there was no guarantee that the gems you were using in development (including dependencies of dependencies like Rack and Active Support) remained the same after a deploy. One recent example that I saw was that
carrierwave added an updated dependency on the newest
activesupport, which depends on Ruby 1.8.7. Without making any change to his
.gems manifest, Heroku failed to deploy his application on their Ruby 1.8.6 stack.
With bundler, this sort of problem can never happen, because you’re always running exactly the same versions of third-party code in production as you are in development and staging. This should increase your confidence in deployments, especially when you come back to an application months after it was originally developed.
Some times, you will need to make small changes to one of your dependencies, and deploy your application with those changes. Of course, in some cases you can make the tweaks via monkey-patching, but in other cases, the only real solution is to change the gem itself.
With bundler, you can simply fork the gem on Github, make your changes, and change the
gem line in your
Gemfile to include a reference to the git repository, like this:
# change this gem "devise" # to this gem "devise", :git => "git://github.com/plataformatec/devise.git"
This behaves exactly the same as a gem version, but uses your tweaks from Github. It participates in dependency resolution just like a regular gem, and can be installed with
bundle install just like a regular gem. Once you’ve added a git repository, you run
bundle install to install it (since the normal
gem command can’t install git repositories).
You can use
:ref flags to specify a particular branch, tag or revision. By default,
:git gems use the
master branch. If you use master or a
:branch, you can update the gem by running
bundle update gem_name. This will check out the latest revision of the branch in question.
Using bundler for the sorts of things that you would have handled manually before should be easier than before. Bundler will handle almost all of the automatable record-keeping for you. While doing so, it offers the incredible guarantee that you will always run the same versions of third-party code.
There are a lot of advanced features of Bundler, and you can learn a lot more about them at the bundler web site.