From DreamHost
Revision as of 05:06, 18 August 2011 by Nachbar (Talk | contribs) (A couple of technical notes: added note about the version of ruby)

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. In other words, you should enable Passenger if you want to access your application via or or If you want to access your application via then use FastCGI instead of passenger.

Configuration Steps

  • 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. You must also specify the location of the 'public' subdirectory of the Ruby on Rails (or other Rack-compliant) application at the same time.
  • Place the code for your application in the directory specified in the previous step.
  • There is no next step! It's that easy.

IMPORTANT NOTE: Whenever the code or configuration files for your application are modified, you must create or update the modification date of the file "tmp/restart.txt" in the application's root directory tree in order trigger 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.)

Basic 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 an appropriately-named HTML or CGI file in the domain's (or subdomain's) "public" subdirectory. If no matching file is found in "public", the request is passed to Passenger's Rack interface. Note that this use of the "public" subdirectory meshes precisely with the way that Ruby on Rails makes use of the same subdirectory.

In order to generate a response, Rack looks for a file named "" in the domain(or subdomain) root directory (i.e. the parent of the domain's "public" directory.) Rack requires that you place the appropriate Ruby code into "" to invoke your desired web framework or application to handle the request. (See Rack for more information about how information is passed through the Rack interface.)

Under normal circumstances, Ruby on Rails (RoR) will automatically create and initialize all of the files and directories needed to interface with Passenger/Rack. When running a RoR application, the only Rack-related files you are likely to modify are possibly adding GEM_PATH information to "" and "touching" the "tmp/restart.txt" file.

The "public" Subdirectory

Passenger maps the directory named "public" to be the document root for your domain/subdomain. In particular, if a static HTML file named "public/index.html" exists, then it will be used as the response for requests for the root document (i.e. "/"). Thus, if you want your application to handle requests for the root document, then you must first remove "public/index.html" if it exists. Please note that, by default, Ruby on Rails creates just such a static "public/index.html" file.

Likewise, a file inside the "public" subdirectory that is named with one of the suffixes recognized by Apache (e.g. "public/foo.cgi" or "public/") will be treated as an executable CGI script in the usual Apache fashion. (See CGI 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

  • Output to STDERR for processes run through the Rack interface is directed to the master Apache error log file rather than the domain/subdomain specific log file. You do not have direct access to the master log file. This limitation can make debugging initialization errors (in particular syntax errors and gem resolution issues) tricky. Passenger will often produce an error output webpage including a stack traceback. However, in some cases it does not. If you have a persistent problem and Passenger is not producing sufficiently useful error output, you can try contacting the Dreamhost support staff and ask them to examine the master log file for you. Once a framework (such as RoR) is up and running, its error output is typically handled by the framework's own error logging mechanism. For example, RoR records its error output in a file named "log/production.log".
  • As of this writing, Aug 18, 2011, Passenger on all shared Dreamhost servers uses Ruby 1.8.7. To use a different version of Ruby (and to otherwise gain full control of the operation of your system) you must use a Virtual Private Server.
  • 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.