How To Install Phusion Passenger / mod_rails / mod_passenger on a cPanel box
I couldn’t find any useful references to installing Phusion Passenger / mod_rails / mod_passenger on a cPanel-based Web server so I stumbled on regardless and managed to overcome the problems I encountered on the way. Those problems and my resolution are all wrapped up here for future use.
Disclaimer
These instructions MIGHT NOT WORK FOR YOU. They also might DAMAGE your setup. They shouldn’t, but I need to disclaim that so you can’t complain later. Follow these instructions at your own risk. They work fine for me on a CentOS 4.6 box with cPanel 11.23.4-R26138 and WHM 11.23.2.
First up, install Apache 2.x
Phusion Passenger’s module only works on Apache 2.x, whereas cPanel’s default is, I believe, 1.3. Luckily, cPanel makes it ridiculously easy to update your Apache installation. If you’re already on Apache 2, skip this section.
Note: If you don’t know what version of Apache you’re running, try curl -i http://server.ip.address/junk_url and look at the Server header returned.
To upgrade Apache, go to your main control panel at https://server.ip.address:2087/ and click the “Apache Update” link on the left. You will then see something like this:
I won’t walk through the whole process, but it’s reasonably painless. It takes at least 10 minutes for Apache and PHP to recompile in my experience, but the downtime is only a few seconds when it restarts Apache.
Tip: I’d recommend choosing Apache 2.2 when you get the option, rather than Apache 2.0.
Second, download Passenger / mod_rails
I’ll assume you already have Ruby and RubyGems installed on your server. If not, you’re way too far down the line with reading this article and need to get up to speed with actually getting those on to your box 
Google will help with that!
To install the latest release version of Passenger (rather than the “edge” version on Github), run as root:
gem install passenger
This will download and “install” the files Passenger uses, but won’t install Passenger into Apache, so Passenger isn’t operative yet.
At this point it’s probably useful to have the Passenger User Guide up on screen, just for reference.
An Aside: Errors You Might Be Experiencing If You Tried This Already..
If you follow Passenger’s instructions and run passenger-install-apache2-module at this point and put the relevant files into your Apache config files, you will end up with an error like this when you try to restart Apache:
httpd: Syntax error on line 2315 of /usr/local/apache/conf/httpd.conf: Syntax error on line 1 of /usr/local/apache/conf/includes/post_virtualhost_global.conf: API module structure ‘passenger_module’ in file /usr/local/lib/ruby/gems/1.8/gems/passenger-2.0.2/ext/apache2/mod_passenger.so is garbled - expected signature 41503232 but saw 41503230 - perhaps this is not an Apache module DSO, or was compiled for a different Apache version?
The “default” apxs being run is /usr/sbin/apxs, but this is a hold-over from the Apache 1.3 installation. The Apache 2.2 version is in /usr/local/apache/bin/apxs, so to force that one to be used:
export APXS2=/usr/local/apache/bin/apxs
Another error that can occur is:
/usr/local/apache/include/apr_file_info.h:192: error: `apr_ino_t’ does not name a type
This occurs because the wrong apr-config is being run. To fix that, you need to export yet another environment variable:
export APR_CONFIG=/usr/local/apache/bin/apr-1-config
Third, compile and install the Passenger module within Apache
Now that we have Passenger downloaded, we need to get it to compile itself as an Apache module. To do this, however, we first need to set some environment variables:
export APXS2=/usr/local/apache/bin/apxs
export APR_CONFIG=/usr/local/apache/bin/apr-1-config
Next, run:
passenger-install-apache2-module
All being well, you’ll eventually end up with Passenger telling you to add a few lines to your Apache configuration file (the code you get may differ slightly):
LoadModule passenger_module /usr/local/lib/ruby/gems/1.8/gems/passenger-2.0.2/ext/apache2/mod_passenger.so
PassengerRoot /usr/local/lib/ruby/gems/1.8/gems/passenger-2.0.2
PassengerRuby /usr/local/bin/ruby
Do not add these to the Apache configuration file (httpd.conf) as it suggests. cPanel can overwrite things you add there! Instead, add it to /usr/local/apache/conf/includes/pre_virtualhost_global.conf - this file might not exist yet, but that’s okay.
Finally, stop and start Apache (I prefer stopping and starting to “restart” - that’s just my way):
service httpd stop
service httpd stop
service httpd start
If there were no errors, you should now be cooking with gas! If there were errors, look at the aside above and see if it’s any of those mentioned there. If all else fails, sorry, but just edit that Apache configuration file and comment out / remove the lines you added and then restart Apache again - at least you’ll have a working Web server!
Feel free to post comments here with any experiences, tips, or errors you’re having. I or someone else might be able to help - though there are no promises, of course! Also refer to the Passenger User Guide for further configuration and usage information.
6 Comments