About Passenger

Passenger, aka mod_rails, is the easiest and fastest way to run rails applications. In most cases, it requires zero configuration: if passenger detects that a docroot is the public folder of a rails application, it will try to spawn the rails application as the user who owns environment.rb.

Passenger then keeps a pool of processes for the rails application, creating new one when needed and removing ones that have not been used in a while. The default timeout is 300 seconds, which is pretty short for a site that gets very little traffic. It means that there will be a slow response to view the website for the first time if all the processes have been shut down.

You can increase the timeout with PassengerPoolIdleTime

Prepare the system

On a Debian system, the package libapache2-mod-passenger provides mod_rails and is available in Squeeze. You can also install it on a Lenny (stable) system by using Backports.org. If you install libapache2-mod-passenger via apt/aptitude, you do not need to do the below gem/build process, you can also skip the next section “Install passenger” and go right to “Deploying to a virtual host’s root”.

# apt-get install rubygems mysql-server ruby libmysql-ruby rdoc1.8 ri1.8 apache2-mpm-prefork ruby1.8-dev build-essential apache2-prefork-dev libopenssl-ruby1.8
# gem install rails --no-ri --no-rdoc
# gem install passenger --no-ri --no-rdoc

mod_rails may work with apache2-mpm-worker, but is only currently tested to work with apache2-mpm-prefork.

Passenger gem includes many executables. On debian, using the default rubygems package, they will be installed in /var/lib/gems/1.8/bin.

One silly way to make them easy to execute:

ln -s /var/lib/gems/1.8/bin/* /usr/local/bin

Although this should not be necessary with newer versions.

Install passenger

# /var/lib/gems/1.8/bin/passenger-install-apache2-module

If you get an error message about undefined method `require_gem', then edit passenger-install-apache2-module and replace require_gem with simply gem.

Make apache load passenger_module:

codetitle. /etc/apache2/mods-available/passenger.load

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.0.1/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.0.1
PassengerRuby /usr/bin/ruby1.8

(or whatever code the passenger-install script tells you you need to added to apache. If you use the debian package for rubygems, the paths will be /var/lib/gems/1.8/… but if you installed rubygems then the path will be /usr/lib/ruby/gems/1.8/…)

enable passenger.load in mods-enabled:
bc. # a2enmod passenger

Deploying to a virtual host’s root

(from http://www.modrails.com/documentation/Users%20guide.html#_deploying_a_ruby_on_rails_app lication)

Add a virtual host entry to your Apache configuration file. The virtual host’s document root must point to your Ruby on Rails application’s public folder. For example:

<VirtualHost *:80>
    ServerName myrailsapp.org
    DocumentRoot /usr/apps/myrailsapp/public
</VirtualHost>

Then restart Apache. The application has now been deployed.

NOTE: if you have a public/.htaccess file in your rails application, get rid of it! mod_rails doesn’t work with it, and it is not needed with mod_rails.

Deploying to a sub URI

(from http://www.modrails.com/documentation/Users%20guide.html#_deploying_a_ruby_on_rails_app lication)

Suppose that you already have a virtual host:

<VirtualHost *:80>
    ServerName domain.org
    DocumentRoot /var/www
</VirtualHost>

And you want your Ruby on Rails application to be accessible from the URL domain.org/railsapp

To do this, make a symlink from your Ruby on Rails application’s public folder to a directory in the document root. For example:

$ ln -s /usr/app/myrailsapp/public /var/www/railsapp

Next, add a RailsBaseURI option to the virtual host configuration:

<VirtualHost *:80>
    ServerName domain.org
    DocumentRoot /var/www
    RailsBaseURI /railsapp
</VirtualHost>

Then restart Apache. The application has now been deployed. Add additional RailsBaseURI lines for additional rails applications.

Restarting mod_rails processes

Here is code to make capistrano restart after a deploy:

namespace :passenger do
  desc "Restart rails application"
  task :restart do
    run "touch #{current_path}/tmp/restart.txt"
  end

  # requires root
  desc "Check memory stats"
  task :memory do
    sudo "passenger-memory-stats"
  end

  # requires root
  desc "Check status of rails processes"
  task :status do
    sudo "passenger-status"
  end
end

after :deploy, "passenger:restart"

Getting information

Passenger comes with some handy commands to query the status of running rails applications:

passenger-status

return general info on how many active processes you have going:

----------- General information -----------
max      = 6
count    = 1
active   = 0
inactive = 1

----------- Applications -----------
/usr/apps/crabgrass/releases/20080603023407: 
  PID: 19487     Sessions: 0


passenger-memory-stats 
-------------- Apache processes --------------
PID    PPID   Threads  VMSize   Private  Name
----------------------------------------------
19458  1      1        12.2 MB  0.4 MB   /usr/sbin/apache2 -k start
19464  19458  1        12.5 MB  0.5 MB   /usr/sbin/apache2 -k start
19465  19458  1        12.4 MB  0.2 MB   /usr/sbin/apache2 -k start
19466  19458  1        12.4 MB  0.2 MB   /usr/sbin/apache2 -k start
19467  19458  1        12.4 MB  0.3 MB   /usr/sbin/apache2 -k start
19468  19458  1        12.4 MB  0.2 MB   /usr/sbin/apache2 -k start
19477  19458  1        12.4 MB  0.2 MB   /usr/sbin/apache2 -k start
### Processes: 7
### Total private dirty RSS: 2.04 MB

--------- Passenger processes ---------
PID    Threads  VMSize   Private  Name
---------------------------------------
19461  9        3.9 MB   0.2 MB   /usr/lib/ruby/gems/1.8/gems/passenger-2.0.1/ext/apache2/ApplicationPoolServerExecutable 0 /usr/lib/ruby/gems/1.8/gems/passenger-2.0.1/bin/passenger-spawn-server  /usr/bin/ruby1.8  /tmp/passenger_status.19458.fifo
19469  2        16.2 MB  5.4 MB   Passenger spawn server
19480  1        32.1 MB  18.7 MB  Passenger FrameworkSpawner: 2.0.2
19483  1        52.6 MB  27.4 MB  Passenger ApplicationSpawner: /usr/apps/crabgrass/releases/20080603023407
19487  1        57.7 MB  32.5 MB  Rails: /usr/apps/crabgrass/releases/20080603023407
### Processes: 5
### Total private dirty RSS: 84.24 MB