Phusion Passenger on cPanel/WHM

December 31, 2011. Posted by Travis in Development, Ruby

Phusion Passenger is an excellent resource which makes deploying your Ruby or Rails app extremely easy. It has suport for both Apache and Nginx. There are plenty of guides online for installation, however we came across a scenario where we needed to deploy an app to an apache2 environment with WHM/cPanel installed.

First you must install the passenger gem:

 gem install passenger

Then you need to run the passenger installer. Assuming it runs without errors, it will give you 2 pieces of code to put in various places, which is what I'm going to talk about in this tutorial.

 passenger-install-apache2-module
 

The first block of code that the installer will tell you to put is the following into your apache configuration file:

 # Load Passenger
 LoadModule passenger_module /usr/local/lib/ruby/gems/1.9.1/gems/passenger-3.0.11/ext/apache2/mod_passenger.so
 PassengerRoot /usr/local/lib/ruby/gems/1.9.1/gems/passenger-3.0.11
 PassengerRuby /usr/local/bin/ruby
 

Note: Your version may be different than what is above. I'd recommend you copy and paste it directly from the output of the installer.

While you could put it into your httpd.conf, you will lose these changes when an update takes place, thanks to cPanel. So, instead of placing this in httpd.conf, place the above 3 lines of code into /usr/local/apache/conf/includes/pre_main_global.conf

The second part of the installer is going to tell you to input the following code into your apache config file

 <VirtualHost *:80>
     ServerName www.domain.org
     DocumentRoot /home/username/path-to-app/public
     <Directory /home/username/path-to-app/public>
         Allow from all
         Options -MultiViews
     </Directory>
 </VirtualHost>
 

If you look in httpd.conf, you will see all the virtual host blocks that are in there. Find the one for your domain, and you will see the following: 

 # To customize this VirtualHost use an include file at the following location 
 # "/usr/local/apache/conf/userdata/std/2/username/domain.org/*.conf"
 

So instead of modifying httpd.conf directly, we need to create a config file, tell apache to check for includes, automatically update httpd.conf, distill, then restart. Instead of using vi, you can also use vim, pico or the editor of your choice. The filename doesn't matter, I used extra.conf here.

 mkdir -p /usr/local/apache/conf/userdata/std/2/username/domain.org/
 vi /usr/local/apache/conf/userdata/std/2/username/domain.org/extra.conf
 

Then put the following into this file:

 DocumentRoot /home/username/path-to-app/public
   <Directory /home/username/path-to-app/public>
     Allow from all
     Options -MultiViews
   </Directory>
 

Next run the following:

 /scripts/ensure_vhost_includes --user=username
 /usr/local/cpanel/bin/apache_conf_distiller --update
 /usr/local/cpanel/bin/build_apache_conf
 /etc/init.d/httpd restart
 

That's it! You should now visit your url and see the Passenger screen if there are any errors, or you'll see your app live if you've set it up correctly!