From DreamHost
Revision as of 06:17, 15 August 2011 by Nachbar (Talk | contribs)

Jump to: navigation, search

DreamHost supports Passenger, free on every hosting plan!

Enterprise logo.png

For help with Rails installations using Passenger, check here: Passenger Troubleshooting.


Passenger [1] (informally also known as mod_rails and mod_rack) is a module for the Apache HTTP Server that greatly simplifies the deployment of Ruby applications, in particular those built using the Ruby on Rails framework. The software is developed by a small company called Phusion. Passenger is the preferred way to deploy and host Ruby on Rails applications across all DreamHost servers.

Use of Passenger vs. FastCGI

Passenger should only be enabled if you intend to run a Ruby on Rails (RoR) or other Ruby/Python-based program as the sole application for the entire domain or sub-domain. Passenger directs essentially all requests for the designated domain/subdomain to the associated Rack-compliant application. So it's best to leave Passenger disabled if you do not actually need it. Eg, you should enable Passenger if you want to access your application via or or . If you want to access your application at then use FastCGI instead of passenger.

Fast Start

  • To enable Passenger, edit any of your fully hosted domains or add a new domain (or sub-domain) from the Manage Domains area of our web panel, and check the Passenger (Ruby/Python apps only) option.
  • Once Passenger is enabled on your domain just set the web directory to the 'public' directory of the Ruby on Rails (or other Rack-compliant) application.
  • There is no next step! It's that easy.
  • IMPORTANT NOTE: Whenever the code or configuration files for your application has changed, creating or updating the modification date of the file "tmp/restart.txt" in the application's root directory tree will tell Passenger to reinitialize the application. Passenger caches many resources and so changes will generally not be recognized unless the modification date of "tmp/restart.txt" is changed. The most common method to make this change is to invoke "touch tmp/restart.txt" from the shell. (Ruby on Rails automatically creates a directory named "tmp". If you are creating non-RoR application, you may need to create the "tmp" directory manually.)

Model of Operation

When a request is made to a domain (or subdomain) with Passenger enabled, the Apache HTTP Server passes the request to Passenger. Passenger first looks for the file in the domain (or subdomain) "public" directory. If a matching file is not found in public, the request is passed to the Rack interface module. Rack looks for a file named "" in the domain(or subdomain) root directory (i.e. the parent of the domain's "public" directory.) The file contains Ruby code which in turn invokes the desired web framework or application. (See Rack for more information.)

Use with Other Web Frameworks

Passenger is most often used in conjunction with Ruby on Rails. However, it has been known to work with a variety of other Rack-compliant web frameworks including (but not limited to) Camping, Padrino, Sinatra, and Ramaze. However, little or no support is provided by Dreamhost for these other frameworks.

A couple of technical notes

  • Passenger and Mongrel fulfill very much the same roles so you most likely do NOT want to be using both of them on the same domain or website.
  • Activating Passenger on a domain will break the phpMyAdmin on any subdomain under the domain. To use phpMyAdmin and Passenger, you must have a non-Passenger-enabled domain with an active phpMyAdmin.
  • In the interest of ease of use and 'Upload and Go' functionality, Passenger disables some mod_rewrite functionality. That means it will automatically override an existing 'dispatch.fcgi' setup you have in place. This is not a problem for your Rails application but it may have other side effects (such as breaking other mod_rewrite rules you have set up). If this causes a problem for your website, contact our support team and we can probably get things working like they did previously for you.
  • Passenger automatically launches applications and leaves them running as long as they are not idle. It also caches the code for Ruby on Rails itself to speed up application launching.
  • You can use your local gem repository if you:
if ENV['RAILS_ENV'] == 'production'  # don't bother on dev
  ENV['GEM_PATH'] = '/home/USERNAME/.gems' #+ ':/usr/lib/ruby/gems/1.8'  # Need this or Passenger fails to start
  require '/home/USERNAME/.gems/gems/RedCloth-4.1.9/lib/redcloth.rb'  # Need this for EACH LOCAL gem you want to use, otherwise it uses the ones in /usr/lib

in the config/environment.rb file after the require boot.rb line. The same path should be set in shell's environment variables GEM_HOME and GEM_PATH so you can use the gem program to install/upgrade your own gems. It seems you also need to clear the existing gem paths after setting the path, or it (inconsistently) ignores whatever you've set, according to [the Phusion Blog]. You can reload the config file by typing "touch tmp/restart.txt" in your base directory.

  • User:Bobstiles Passenger doesn't delete the tmp/restart.txt file, but it looks at the timestamp instead and leaves the file.
  • As of 4 Aug 2008, Passenger only supports Rails 2.0.2. I have set up a couple of sites (October 2008) running with Rails 1.2.6, and they seem to behave nicely.
  • User:Bobstiles As of 12 Dec 2009, Passenger seems to only need to know where your local gems are. You don't have to add any special require statements. The above config doesn't work. Use this.
if ENV['RAILS_ENV'] == 'production'  # don't bother on dev
  ENV['GEM_PATH'] = '/home/USERNAME/.gems' + ':/usr/lib/ruby/gems/1.8'
  • User:davidonlaptop For Rails 2.3.8, Bobstiles's above code needs to be BEFORE the boot line :
RAILS_GEM_VERSION = '2.3.8' unless defined? RAILS_GEM_VERSION

if ENV['RAILS_ENV'] == 'production'  # don't bother on dev
  ENV['GEM_PATH'] = '/home/USERNAME/.gems' + ':/usr/lib/ruby/gems/1.8'

require File.join(File.dirname(__FILE__), 'boot')

  • For some reason, Passenger will not use the 'rails' installation in your local gems repository. However, it will be able to load all other gems. To run Passenger with Rails 2.1.0, freeze rails into your vendor/ directory. To do that, run the following command on the server. Make sure the current directory is the Rails app directory.
rake rails:freeze:edge TAG=rel_2-1-0

This will work, but having Rails in your local gem directory will not. The same method applies to all Rails versions above 2.1.0 .


Using Capistrano with DH RoR on Passenger works well. Use the Manage Domains area of our web panel to set the domain's web directory to:

# access app 'foo' via  or via
# Set web directory in the DH panel to:
# In your Capistrano deploy/production.rb file:
set :deploy_to, "/home/DH_user_name/{application}"
# Where DH_user_name is your CGI-runs-as user field in the domain edit screen from the DH Panel

If you need to use a different rails environment than 'production', take a look at this.

Passenger and Python/WSGI

Passenger provides "proof of concept" support for WSGI-compliant Python applications. See the Passenger WSGI article for more information.

See Also

External Links

  • The Passenger Documentation on Application Deployment - At Dreamhost, Ruby on Rails applications are reached through the Rack interface. So the relevant Passenger documentation is in the "Rack Deployment" section not the "Ruby on Rails Deployment" section. Also, you do not need to concern yourself with the Apache configuration files. Dreamhost automatically configures those for you.