How to deploy bundled applications
Gemfile.lockto source control, but ignore the
.bundlefolder, which is specific to each machine.
$ echo ".bundle" >> .gitignore $ git add Gemfile Gemfile.lock .gitignore $ git commit -m "Add Bundler support"
Manual deploymentIn your deploy script, after updating to the latest code, install your bundle to the
vendor/bundledirectory, 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
bundle package, the cached
gems will be used automatically.
Automatic deployment with Capistrano
cap deploywill now automatically run
bundle installon 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
cap -e bundle:install.
Automatic deployment with VladThere is a default Vlad task available. To make it available, add this line to the Vlad
vlad:bundle:installtask will be available for use. Make sure it is run as part of your deploy. For example:
task "vlad:deploy" => %w[ vlad:update vlad:bundle:install vlad:start_app vlad:cleanup ]
After deployingMake sure to use
bundle execto run any executables from gems in the bundle
$ bundle exec rake db:setup
--binstubsoption on the install command to generate executable binaries that can be used instead of
HerokuWhen 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
`bundle install --deployment`. If you want to exclude certain groups using the
--withoutoption, you need to use
$ heroku config:set BUNDLE_WITHOUT="test development" --app app_name
Deploying Your Application
bundle install, bundler will (by default), install your gems to your system repository of gems. This means that they will show up in
gem list. 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
user that boots the application may not have access to them. For instance, Passenger
runs its Ruby subprocesses with the user
nobody, 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
bundle install when some
third-party dependencies have changed).
As a result, bundler comes with a
--deployment 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
--deployment flags adds the following defaults:
Instead of installing gems to the system location, bundler will install gems to
vendor/bundleinside your application. Bundler will transparently remember this location when you invoke it inside your application (with
- Bundler will not use gems already installed to your system, even if they exist.
If you have run
bundle pack, checked in the
vendor/cachedirectory, and do not have any git gems, Bundler will not contact the internet while installing your bundle.
Bundler will require a
Gemfile.locksnapshot, and fail if you did not provide one.
Bundler will not transparently update your
Gemfile.lockif it is out of date with your
If you use Capistrano, you should symlink
shared/vendor_bundle 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
vendor/bundle, 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
--deployment flag requires an up-to-date
ensure that the testing you have done (in development and staging) actually reflects the
code you put into production. You can run
bundle check before deploying
your application to make sure that your
Gemfile.lock is up-to-date. Note
that it will always be up-to-date if you have run
successfully booted your application (or run your tests) since the last time you changed