Passenger overview

Passenger is an open source web and application server that greatly simplifies the deployment of Ruby applications, Python, and Node.js. Passenger is the preferred way to deploy and host Ruby on Rails applications across all DreamHost servers and is free on every DreamHost hosting plan.

Basic operation

The following are the basic actions that take place once a file is requested from a domain running Passenger and Ruby on Rails:

  1. When a request is made to a domain/subdomain, the Apache HTTP Server passes the request to Passenger.
  2. Passenger first looks for an appropriately-named HTML or CGI file in the domain/subdomain's /public subdirectory.
  3. If no matching file is found, the request is passed to Passenger's Rack interface.
  4. Note that this use of the /public subdirectory meshes precisely with the way that Ruby on Rails makes use of the same subdirectory.
  5. In order to generate a response, Rack looks for a file named "config.ru" in the domain/subdomain's root directory (i.e., the parent of the domain's /public subdirectory).
  6. Rack requires that you place the appropriate Ruby code into "config.ru" to invoke your desired web framework or application to handle the request.

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 "config.ru" and "touching" the "tmp/restart.txt" file.

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 subdomain. Passenger directs 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 only enable Passenger if you want to access your application via the following three URLs:

  • myapp.example.com
  • www.example.com
  • www.myapp.example.com

If you want to access your application via www.example.com/path-to-myapp then use FastCGI instead of passenger.

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 April 2015, 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 VPS and install RVM.
  • Passenger and Mongrel fulfill very much the same roles so you most likely do NOT want to use both of them on the same domain or website.
  • Activating Passenger on a domain will break the phpMyAdmin interface 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, try using the FastCGI method.
  • 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 use the following in the config/environment.rb file:
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
end

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

The same path should be set in your shell's environment variables GEM_HOME and GEM_PATH so you can use the gem program to install/upgrade your own gems. You can reload the config file by running "touch tmp/restart.txt" in your base directory.

Troubleshooting

For common troubleshooting solutions, please visit the Passenger Troubleshooting article.

See also

Passenger

Ruby

Python

Node.js