Edit page

Ruby Bundler support

Passenger has automatic support for Ruby's Bundler tool. The support consists of loading your application under the environment defined by your Gemfile. In other words, Passenger automatically loads your application as if bundle exec was used.

The Bundler support works as follows:

  • If you have a .bundle/environment.rb in your application directory, then Passenger will require that file before loading your application. This is a mechanism used by ancient versions of Bundler, but we still support it.
  • Otherwise, if you have a Gemfile, then Passenger will automatically call Bundler.setup before loading your application.

It is possible that your application also calls Bundler.setup during loading, e.g. in config.ru or in config/boot.rb. This is the case with Rails >= 3. This leads to Bundler.setup being called twice, once before the application startup file is required and once during application startup. However this is harmless and doesn't have any negative effects.

Passenger assumes that you're using Bundler >= 0.9.5. If you don't want Passenger to run its Bundler support code, e.g. because you need to use an older version of Bundler with an incompatible API or because you use a system other than Bundler, then you can override Passenger's Bundler support code by creating an empty file config/setup_load_paths.rb. If this file exists then Passenger will load that file instead of going through the Bundler loading procedure as documented above. In this file you can do whatever you need to setup Bundler or a similar system.

Does Passenger itself need to be added to the Gemfile?

It is never necessary to add Passenger to the application's Gemfile, though it is allowed.

In case of Passenger Standalone, it is not necessary to execute the passenger command through bundle exec. The reason for this is because Passenger automatically loads the Gemfile environment. Most other Ruby application servers do not automatically load the Gemfile environment, which is why they must be added to the Gemfile and be executed with bundle exec.

Even when your application uses any of the Passenger Ruby APIs (e.g. the smart spawning hooks), you still do not need to add Passenger to the Gemfile. The only thing you need to do is to put Passenger Ruby API calls inside if blocks that check whether Passenger is active, by checking whether the PhusionPassenger namespace is defined:

if defined?(PhusionPassenger)
  ...
end

Having said that, our installation guides and deployment tutorials on Passenger Standalone do instruct you to add Passenger to the Gemfile. We only recommend that because the process is familiar to Ruby developers, not because it is strictly necessary.