Installing Ruby on Rails with Passenger on a cPanel Server

4.4/5 - (28 votes)

With the Ruby developer community continuing to grow, we often get requests for Ruby support from providers wanting to be able to offer their customers the ability to run Rails applications.  We do not recommend using the current Ruby on Rails feature provided by cPanel, as it relies on the CentOS-provided version of Ruby as well as Mongrel 1, both of which are extremely outdated. While cPanel has indicated they have plans to implement Phusion Passenger-based RoR support, there has been little indication this project is still moving along.

We want to reiterate that a server running cPanel is probably not the best production platform for a production RoR application to be housed, but it’s certainly possible and sustainable.  And for some people, it may be their only option.

These instructions have been adapted from Digital Ocean’s instructions for Rails deployment on a bare CentOS 6 box.  This guide also assumes the following is true on your server:

1) You are on a cPanel server (if not, please refer to Digital Ocean’s guide linked above)
2) You have used EasyApache to install Apache 2.2 or Apache 2.4. To confirm this:

root@server [~]# httpd -v
 Server version: Apache/2.4.12 (Unix)
 Server built: May 27 2015 19:16:47
 Cpanel::Easy::Apache v3.30.0 rev9999

3) Your server has at least 1GB of memory, though 1.5GB is preferred for the installation itself
4) You have root-level access

Install ruby

Some guides will advise simply using Yum to install Ruby, however, we do not recommend that since CentOS uses a very old version. Use RVM (Ruby Version Manager) instead:

gpg2 --keyserver hkp:// --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -L | bash -s stable
source /etc/profile.d/
rvm requirements

At the time of this writing, 2.2.2 is the latest Ruby version. You might want to go to the Ruby website to see what the most recent version is.  Use that version in the below command:

rvm install 2.2.3

Configure 2.2.2 to be the default Ruby version:

rvm use 2.2.3 --default

Now, install Rails:

gem install rails

Confirm Ruby and Rails are installed:

root@server [~]# ruby -v
ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]root@server [~]# rails -v
Rails 4.2.4

Install Phusion Passenger

gem install passenger
yum -y install curl-devel sqlite-devel

If you get an unclear error on the last step, the most likely cause is running out of memory. While 1GB is recommended, we’ve seen that it often takes up to 1.5GB or more of RAM for the modules to compile.

Now we need to add this to our Apache configuration. On cPanel servers, this is the main point of difference from non-cPanel servers since you cannot directly edit certain configurations in httpd.conf. So you’ll need to create an include. In a text editor, create the following file:


Inside of this file, add the following lines:

LoadModule passenger_module /usr/local/rvm/gems/ruby-2.2.3/gems/passenger-5.0.24/buildout/apache2/
PassengerRoot /usr/local/rvm/gems/ruby-2.2.3/gems/passenger-5.0.24 
PassengerDefaultRuby /usr/local/rvm/wrappers/ruby-2.2.3/ruby

(There are three lines here – the formatting on our website may alter how it appears)

With the above configuration, you’ll want to make sure you’re using the correct paths based on the versions of Ruby an Passenger you installed.

Now open this file:


And add the following line:

Include “/usr/local/apache/conf/passenger.conf”

Then rebuild the configuration and restart Apache:

 service httpd restart


Create a new cPanel account or use an existing one. Go into that user’s public_html:

cd /home/rubyapp/public_html
 rails new testapp
 cd testapp

Open GemFile and add this line before ‘end’:

gem ‘therubyracer’


bundle install
 rake db:migrate

From here, and in general, you’ll need to alter the domain’s document root to point to the ‘public’ folder of the application. On cPanel servers, you do this by editing /var/cpanel/userdata/$user/domain.

You’ll also need to create an include for the application environment:

mkdir /usr/local/apache/conf/userdata/std/2_4/$user/$domain/

(Hint: if you look at the Virtual Host for the domain in httpd.conf, you’ll see the path for the include you need to create)

Update: A reader commented on the following script that helps generate includes for this:

Create a file in this folder called rails.conf with the following:

RackEnv development
<Directory /home/$user/public_html/testapp/public>
Options -MultiViews

Make sure the domain’s document root is pointed to the same folder.  For an addon or subdomain you can specify the directory when it is created in cPanel, or otherwise edit it in /var/cpanel/userdata/$user/$domain.

Then comment out the include line for this virtual host in httpd.conf and run the following commands:

 service httpd restart

You should be able to now go to the domain you set up and see the “Welcome aboard” message in your browser, indicating that Ruby and Passenger are working.


  1. Anderson Alvarez Vásquez Reply

    Hi, after making this change, enter that url Rails applications, you need to restart Apache each time a new Rails application is desired? Thank you

  2. Satchel Paige Reply

    Great article! I do have a few questions:

    When I get to the ‘bundle install’ line my server tells me “Don’t run Bundler as root. Bundler can ask for sudo if it is needed, and installing your bundle as root will break this application for all non-root users on this machine.” Am I doing something wrong here…or is this not the case?

    Will this setup work for multiple users using Ruby?

  3. Teknicom Web Reply

    Why should I set the RackEnv variable to development when I am deploying? Shouldn’t this be production instead? If I deploy in development mode, how can I continue to develop locally when I have to change the env variable to match server and production requirements? Please help.

    Great guide btw. I managed to get my app deployed using these instructions but it’s running in dev mode that’s the only problem right now

    1. Vanessa Vasile Reply

      These instructions are more of an example. If you want to use a production environment, set it to production. You can have more than one directive in the apache config, pointing to different areas of the application. The application just has to match the environment it’s being run under.

  4. Satchel Paige Reply

    Running the initial ‘rails new testapp’ results in the system asking for sudo privileges for me.
    With an error that reads, “Your user account isn’t allowed to install to the system Rubygems.
    You can cancel this installation and run:

    bundle install –path vendor/bundle

    to install the gems into ./vendor/bundle/, or you can enter your password
    and install the bundled gems to Rubygems using sudo.”

    Doing the initial ‘rails new testapp -B’ to not run the bundle install, and then doing a manual ‘bundle install –path vendor/bundle’ does seem to work as a workaround. Subsequent ‘bundle install’ commands will work fine after this, but am wondering how others have it working without doing anything special. To me, this error makes sense, because as a user when I check my environment variables, the GEM_PATH is listed as GEM_PATH=/usr/local/rvm/gems/ruby-2.3.0:/usr/local/rvm/gems/ruby-2.3.0@global which a regular user would not have access too.

  5. Manuel Arellana Reply

    Thank you for this tutorial, very helpful.

    I follow all your steps, But when try to restart apache I get these error:

    [/usr/local/apache/conf/includes]# service httpd restart
    httpd: Syntax error on line 28 of /usr/local/apache/conf/httpd.conf: Syntax error on line 1 of /usr/local/apache/conf/includes/pre_main_global.conf: Syntax error on line 1 of /usr/local/apache/conf/passenger.conf: Cannot load /usr/local/rvm/gems/ruby-1.8.7-p374@scacr_rails2.2.2/gems/passenger-5.0.25/buildout/apache2/ into server: /usr/local/rvm/gems/ruby-1.8.7-p374@scacr_rails2.2.2/gems/passenger-5.0.25/buildout/apache2/ undefined symbol: ap_get_server_version

    Where I need to define ap_get_server_version symbol ?

    Thanks in advance

  6. Manuel Arellana Reply

    I found the error.

    I the step: passenger-install-apache2-module you need to place the correct path of apx2

    passenger-install-apache2-module –apxs2-path “/usr/local/apache/bin/apxs”


  7. Nicholas Wilkins Reply


    I have been trying to install Passenger alongside Ruby and Rails on a brand new cPanel server running on VMware.

    [root@cpanel ~]# httpd -v
    Server version: Apache/2.4.23 (cPanel)
    Server built: Aug 24 2016 19:30:51

    The installation of Ruby Version Manager along with Ruby and Rails was very straightforward.

    [root@cpanel ~]# ruby -v
    ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-linux]
    [root@cpanel ~]# rails -v

    My issue comes when trying to run the passenger-install-apache2-module. I get errors about the following required software:

    * Checking for Apache 2 development headers…
    Found: no
    * Checking for Apache Portable Runtime (APR) development headers…
    Found: no
    * Checking for Apache Portable Runtime Utility (APU) development headers…
    Found: no

    My understanding is these are installed via cPanel but the installer just doesn’t know where they are.

    Would you be able to assist me with resolving the above errors at all please? This is the last stumbling block 

    Many Thanks


    1. M L Reply


      I’m having the same issues as Nicholas Wilkins:

      Location: /usr/include/zlib.h
      * Checking for Apache 2…
      Found: no
      * Checking for Apache 2 development headers…
      Found: yes
      Location of apxs2: /usr/sbin/apxs

      We are running Easy apache 4 i think the “passenger-install-apache2-module” cant find the default path.

  8. Divyang Reply

    Does this work on CentOS 7 and EA 4?
    if not What do I need to do different to make it work with it?

    Great post! Thank you for supporting. Keep it up!

  9. Pingback: mod_passenger with WHM + Centos7 | web i9

  10. Pingback: Deploying rails application on cpanel WHM on centos 7 - TechTalk7

Leave a Reply

Your email address will not be published. Required fields are marked *

Log in