Rails 3.x /w Phusion Passenger in cPanel


Dec 18, 2005
Thanks to Tristan Wallace @ cPanel for the instructions on getting Phusion Passenger to work properly!

Installing mod_rails and Rails 3.0.9 on a cPanel machine | cPanel Blog

NOTE: Rails functionality in cPanel will be BROKEN if you update Rails to 3.x. Rails 3.x is not officially supported in cPanel/WHM 11.34/11.36. This means you have to create rails apps manually and make direct edits to the Apache configuration using the distiller to save them. This will break clients' ability to add rails apps easily from their cPanel accounts. Only do this if a rails app absolutely requires Rails 3.x (e.g redmine 2.x). This will also break any existing Rails apps as cPanel uses a different framework (Mongrel) for Rails 2.x

NOTE: git is required for this install. cPanel's official stance on git is to install it from source, as installing it from repositories requires that perl modules be installed from repositories as well, which is not supported in cPanel/WHM 11.34. See this link for instructions on installing git from source: Git - Installing Git

First, install ruby and Ruby on Rails normally if they have not been already with:

Once installed, force an install of the latest rails version with:

gem install rails
You will need to install the latest version of the passenger gem in order for it to work. Do the following:

cd /usr/local/src
git clone https://github.com/FooBarWidget/passenger.git 
cd passenger
gem build passenger.gemspec
gem install passenger-*.gem
rm -rf /usr/local/src/passenger
Make sure you note the version number, as that will be needed when configuring passenger in Apache.

Now that passenger is properly installed, you can use it to compile the mod_passenger module for apache. Note that this action requires temporarily setting /tmp as executable

mount -o remount,rw,exec,nosuid,loop=/dev/loop0 /usr/tmpDSK
mount -o remount,rw,exec,nosuid /tmp
mount -o remount,rw,exec,nosuid /var/tmp
mount -o remount,rw,noexec,nosuid,loop=/dev/loop0 /usr/tmpDSK
mount -o remount,rw,noexec,nosuid /tmp
mount -o remount,rw,noexec,nosuid /var/tmp
Now that the module is compiled into Apache, you can load it. Edit the Pre Main Global Include. You can do this in WHM under Service Configuration > Apache Configuration > Include Editor > Select Pre Main Global, or directly in SSH in the file /usr/local/apache/conf/includes/pre_main_global.conf. Append the following to the include:

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-4.0.0.rc4/libout/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-4.0.0.rc4
PassengerRuby /usr/bin/ruby
Ensure that you are using the correct directory when loading the actual passenger module and the root for the gem

Now, backup your main Apache config file and distill the changes using cPanel's Apache Distiller

cp /usr/local/apache/conf/httpd.conf /usr/local/apache/conf/httpd.conf.bak-modrails
/usr/local/cpanel/bin/apache_conf_distiller --update
/etc/init.d/httpd restart
If you get any errors, this is likely because your paths are incorrect for the LoadModule and PassengerRoot directives

Rails 3.x /w mod_passenger is now installed. You can use the following to create a test rails application (replace username with a cPanel test account in your system)

rails new /home/username/hello
cd /home/username/hello
rails generate scaffold person name:string password:string email:string age:integer
rake db:create:all
rake db:migrate
ln -s /home/username/hello/public /home/username/public_html/hello
cd /home/username/hello/db
cp development.sqlite3 production.sqlite3
chown -R username:username /home/username/hello
echo "RailsBaseURI /hello" >> /home/username/hello/public/.htaccess
/etc/init.d/httpd graceful
The following will create the rails app, define the parameters, create a sqlite database, populate the database, setup the Rails URI, clone the development database to production, set permissions, and finally create the rails app in .htaccess.


Staff member
Apr 11, 2011
Sorry to drag up this old thread, but the blog post to which cPBrianW refers is currently offline - does anyone have a copy of it?
It was a third-party URL that appears to be down. However, you should be able to search for "cPanel + Ruby on Rails + Phusion Passenger" on Google to see other sites that host the same tutorial. Note that these are third-party instructions not supported or maintained by cPanel.