This article was written for Bundler version 1.0. If you are using a later version of Bundler, the commands and code here may or may not work. If in doubt refer to the Bundler home page.
Bundler helps you deploy applications further than running bundle install on your machines. You can install all your gems to your application directory in the vendor directory. This allows you to run a bundle install once and deploy to multiple machines at once. This might not be useful to everyone though, if you don't plan on doing something like this it may not be a good idea to use the vendor directory.
In order to install your gems to the vendor directory run the command bundle install --deployment. If you recall, running simply bundle install (without the --deployment command) will install the gems with the gem command line tool in the default location. Running the same command with the --deployment switch will create a vendor/bundle directory (if it doesn't already exist) and install all of the gem dependencies there. If you examine this directory after installing the gems, you'll see a ruby/gems directory just like your normal $GEM_HOME directory.
$ bundle install --deployment Using rake (0.9.2.2) Using i18n (0.6.0) Using multi_json (1.1.0) Using activesupport (3.2.1) Using builder (3.0.0) Using activemodel (3.2.1) Using erubis (2.7.0) Using journey (1.0.2) … Using thor (0.14.6) Using railties (3.2.1) Using rails (3.2.1) Your bundle is complete! It was installed into ./vendor/bundle
As long as you require your gems in the recommended way, all gems will be required from this new gem directory. So it doesn't even matter what gem versions are installed on the system, you can freely copy this application directory with the gem dependencies installed into the vendor directory to any machine with an appropriate Ruby installed.
Running Commands from Gems
Many gems also come with command line tools (like the bundler tool itself). In order to use these from your vendor directory you have to use the bundle tool to run them. Specifically, the bundle exec command. This will search through your vendor directory and execute the command-line application from there.
$ bundle exec rails --version Rails 3.2.1
The .bundle Directory
When you run certain Bundler commands, it will create a .bundle directory, usually with just a config file in it. Unlike the Gemfile and Gemfile.lock files, this file should not be added to source code control. This is something that's intended to be machine-specific, so try to keep it that way.
Where This Can Go Wrong
Bundler only bundles gems. However, your program can rely on things that aren't part of any gem. For example, if you install a gem that interacts with MySQL and uses the MySQL native shared libraries on the system, Bundler cannot bundle this into vendor. Similarly, if the gem relies on any command line tools, operating system specific features, specific environments, etc, Bundler cannot anticipate that.
For this reason, using bundle install --deployment is not a silver bullet for deployment. This is intended for distributing a single application directory around on (hopefully) identical and pre-configured machines. This is not for deployment in general.
Packaging: Best of Both Worlds
What if you want to ease deploying to varied machines? What if these machines don't have access to the Internet? The bundle package command is probably what you're looking for. This will copy all of the .gem package files (which are really just gzipped tarballs) into the vendor/cache directory. Then you can pass the --local switch to bundle install and if the gem is in the cache directory, the gem command won't have to reach out the Internet in order to install the gems.
$ bundle package Using rake (0.9.2.2) Using i18n (0.6.0) … Using railties (3.2.1) Using rails (3.2.1) Your bundle is complete! It was installed into ./vendor/bundle Updating .gem files in vendor/cache * rake-0.9.2.2.gem * i18n-0.6.0.gem … * thor-0.14.6.gem * railties-3.2.1.gem * rails-3.2.1.gem
Since these are the .gem files from the Rubygems repository, not some installed, preconfigured and precompiled form as with bundle install --development, it's safe to copy these from computer to computer. They'll be installed as any other gem would be installed. Just be sure to use the --local switch.
$ bundle install --local
This is also particularly useful if you are using gems that aren't in a public repository. If you're publishing gems to a private repository that the clients won't have access to, you can package them using this command to simplify things quite a bit. The alternative is to try to vendor some gems, but leave others to install. But this complicates things. Bundler exists to make things easier, not more complicated.