Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
160 lines (144 sloc) 7.54 KB
title: How to deploy bundled applications
%h2 How to deploy bundled applications
Before deploying an app that uses Bundler, Add your <code>Gemfile</code>
and <code>Gemfile.lock</code> to source control, but ignore the
<code>.bundle</code> folder, which is specific to each machine.
$ echo ".bundle" >> .gitignore
$ git add Gemfile Gemfile.lock .gitignore
$ git commit -m "Add Bundler support"
Once you have done that, there are two ways to deploy using Bundler:
manually or automatically.
%h3 Manual deployment
In your deploy script, after updating to the latest
code, install your bundle to the <code>vendor/bundle</code>
directory, ensuring all your dependencies are met.
$ bundle install --deployment
Start your application servers as usual, and your
application will use your bundled environment
with the exact same gems you use in development.
If you have run <code>bundle package</code>, the cached
gems will be used automatically.
= link_to 'Learn More: Packing', '/man/bundle-package.1.html', class: 'btn btn-primary'
%h3 Automatic deployment with Capistrano
To pull in the Bundler Cap task, just add this to your
<code>deploy.rb</code> file:
# lang: ruby
require 'bundler/capistrano'
That's it! Running <code>cap deploy</code> will now automatically run
<code>bundle install</code> on the remote server with deployment-friendly
options. A list of options that can be changed is available in the help
for the cap task. To see it, run <code>cap -e bundle:install</code>.
%h3 Automatic deployment with Vlad
There is a default Vlad task available. To make it available, add this line
to the Vlad <code>deploy.rb</code>.
# lang: ruby
require 'bundler/vlad'
Once you have done that, the <code>vlad:bundle:install</code> task will be
available for use. Make sure it is run as part of your deploy. For example:
# lang: ruby
task "vlad:deploy" => %w[
vlad:update vlad:bundle:install vlad:start_app vlad:cleanup
%h3 After deploying
Make sure to use <code>bundle exec</code> to run any executables
from gems in the bundle
$ bundle exec rake db:setup
Alternatively, you can use the <code>--binstubs</code> option on the
install command to generate executable binaries that can be used instead of
<code>bundle exec</code>.
= link_to 'Learn More: Executables', '/man/bundle-exec.1.html', class: 'btn btn-primary'
%h3 Heroku
When you deploy to Heroku, Bundler will be run automatically as long as a Gemfile is present. If you check in your Gemfile.lock, Heroku will run <code>`bundle install --deployment`</code>. If you want to exclude certain groups using the <code>--without</code> option, you need to use <code>`heroku config`</code>.
$ heroku config:set BUNDLE_WITHOUT="test development" --app app_name
= link_to 'Heroku Bundler Documentation', '', class: 'btn btn-primary'
Deploying Your Application
When you run <code>bundle install</code>, bundler will (by default), install your gems
to your system repository of gems. This means that they will show up in <code>gem
list</code>. Additionally, if you are developing a number of applications, you will not
need to download and install gems in common for each application. This is nice for
development, but somewhat problematic for deployment.
In a deployment scenario, the Unix user you deploy with may not have access to install
gems to a system location. Even if the user does (or you use <code>sudo</code>), the
user that boots the application may not have access to them. For instance, Passenger
runs its Ruby subprocesses with the user <code>nobody</code>, a somewhat restricted
user. The tradeoffs in a deployment environment lean more heavily in favor of isolation
(even at the cost of a somewhat slower deploy-time <code>bundle install</code> when some
third-party dependencies have changed).
As a result, bundler comes with a <code>--deployment</code> flag that encapsulates the
best practices for using bundler in a deployment environment. These practices are based
on significant feedback we have received during the development of bundler, as well as a
number of bug reports that mostly reflected a misunderstanding of how to best configure
bundler for deployment. The <code>--deployment</code> flags adds the following defaults:
Instead of installing gems to the system location, bundler will install gems to
<code>vendor/bundle</code> inside your application. Bundler will transparently remember
this location when you invoke it inside your application (with
<code>Bundler.setup</code> and <code>Bundler.require</code>).
Bundler will not use gems already installed to your system, even if they exist.
If you have run <code>bundle pack</code>, checked in the <code>vendor/cache</code>
directory, and do not have any git gems, Bundler will not contact the internet while
installing your bundle.
Bundler will require a <code>Gemfile.lock</code> snapshot, and fail if you did not
provide one.
Bundler will not transparently update your <code>Gemfile.lock</code> if it is out of
date with your <code>Gemfile</code>
If you use Capistrano, you should symlink <code>vendor/bundle</code> to
<code>shared/vendor_bundle</code> so that bundler will share your installed gems between
deployments (making things zippy if you didn't make any changes), but still give you the
benefits of isolation from other applications.
By defaulting the bundle directory to <code>vendor/bundle</code>, and installing your
bundle as part of your deployment process, you can be sure that the same Unix user that
checked out your application also installed the third-party code your application needs.
This means that if Passenger (or Unicorn) can see your application, it can also see its
The <code>--deployment</code> flag requires an up-to-date <code>Gemfile.lock</code> to
ensure that the testing you have done (in development and staging) actually reflects the
code you put into production. You can run <code>bundle check</code> before deploying
your application to make sure that your <code>Gemfile.lock</code> is up-to-date. Note
that it will always be up-to-date if you have run <code>bundle install</code>,
successfully booted your application (or run your tests) since the last time you changed
your <code>Gemfile</code>.