Ruby, Ruby Gem, Rails and Mongrel Troubleshooting Guide

You’ve taken the plunge and installed Ruby on your cPanel system using our /scripts/installruby command. Now, you are preparing to run Rails applications to step into the Web 2.0 world. This guide will cover some of the common issues that might prevent your application from working.

Latest cPanel Versions
For all issues reported, first check the ruby version, rails version, ruby gem version and mongrel version. The current versions that we install are the following:

# ruby -v
ruby 1.8.7 (2009-06-08 patchlevel 173) [i686-linux]
# rails -v
Rails 2.3.8
# gem -v
# gem list mongrel
*** LOCAL GEMS ***
mongrel (1.1.5)

If you have newer versions than the above and installed them manually rather than using our script installer, the issue is likely being caused by a conflict with the version installed and our interface. We do not currently support Rails 3.0.0 due to the differences in how it generates applications and how mongrel does not work with that version of Rails.

Newer versions of Ruby do not work with our gem installer, so if Ruby was manually updated by removing the yum exclusion line in /etc/yum.conf, then that version of Ruby would need to be uninstalled and the compatible versions installed using our script.

Reinstall Ruby
Any time you are going to reinstall Ruby (to obtain the current version we use for Ruby, Rails, Ruby Gem and Mongrel), please do the following steps:

# mv /usr/lib/ruby /usr/lib/ruby.bak
# mv /usr/local/lib/ruby /usr/local/lib/ruby.bak
# mv /usr/bin/ruby /usr/bin/ruby.bak
# mv /usr/local/bin/ruby /usr/local/bin/ruby.bak
# mv /usr/bin/rails /usr/bin/rails.bak
# mv /usr/local/bin/rails /usr/local/bin/rails.bak
# mv /usr/bin/gem /usr/bin/gem.bak
# mv /usr/local/bin/gem /usr/local/bin/gem.bak

By moving the folders, you can a) revert to your prior installation if needed, and b) wipe all existing traces of your Ruby, Rails, Ruby Gem and Mongrel installation. At that point, issuing this command will then install a fresh copy of those components:

# /scripts/installruby

Please note that we can only assist when using compatible, installed versions that our script provides. If you have any issues with reinstalling ruby or any related services, we are happy to help. You are welcome to open a support ticket using WHM > Support Center > Contact cPanel for assistance with getting the right versions installed onto your server.

Common Issue with Applications Not Working
1. Check the Rails version is 2.3.8 or lower
If you are running a version of Rails higher than 2.3.8 such as Rails 3.0.0, Rails applications will not be generated properly in the cPanel interface. This will cause the application to not start. The resolution is to downgrade Rails to a version compatible with cPanel.

To check the rails version, you would run in root SSH the following command:

# rails -v

To downgrade to Rails 2.3.8, you would use the following steps:

# gem uninstall rails
# gem uninstall actionmailer
# gem uninstall activemodel
# gem uninstall actionpack
# gem uninstall activerecord
# gem uninstall activeresource
# gem uninstall activesupport
# gem uninstall railties
# gem install rails -v=2.3.8

2. Mongrel is not running
If mongrel is not running for the application, then the site will not load. This can be determined by simply running a ps aux for the user’s name for mongrel:

# ps aux | grep mongrel | grep username

Replace username with the actual username. Here is an example on my own machine for this command:

# ps aux | grep mongrel | grep admin
admin 19279 0.0 2.3 26312 23264 ? S Dec02 0:03 /usr/bin/ruby /usr/bin/mongrel_rail
start -p 12004 -d -e development -P log/
admin 24185 0.0 3.0 34272 30348 ? S Dec02 0:03 /usr/bin/ruby /usr/bin/mongrel_rails
start -p 12003 -d -e development -P log/

If you do not see any processes running for that user for mongrel, then mongrel is not running. You would want to check the errors in the logs mentioned next to see what is happening.

3. Check the logs
The log files will be at /home/username/rails_apps/appname/log/ location where username is the cPanel username and appname is the name of the application. The main logs to check are mongrel.log and either development.log or production.log depending on which environment type is being used for the application.

In the mongrel log, if the issue is a missing gem, it will normally look like the following entry:

  Status: 500 Internal Server Error
  no such file to load -- mysql

In this instance, you can simply install the needed gem

# gem install gemname

For the above, it would be missing mysql, so you would run:

# gem install mysql

4. Application is getting killed or stopping
If you are running a firewall such as CSF, disable LFD and CSF on the system temporarily in WHM > Plugins > ConfigServer Security & Firewall > Firewall disable

Additionally, if you have prm (process resource monitor) being used, check it is not killing the process.

5. Port is not working
Again, if you are running a firewall, check the port has been whitelisted in the firewall. You can see which port is being used by the application in cPanel > Ruby on Rails > Rails Server URL field (either hovering over it or clicking on it will show the port listed for the application). You can always disable the firewall or stop it temporarily to see if the firewall is the cause for the port not working.

Gem specific tips
1. To check which gems are installed locally

Use the following command:

# gem list


# gem list --local

You can see a list of all remote gems (those you can install) using this command:

# gem list --remote

2. Install Gem specific version
Of note, you can install any gem specific version by using that -v=# tag so long as the version is in the gem repository. Let’s say you want to install sqlite3-ruby version 1.2.5, you would run:

# gem install sqlite3-ruby -v=1.2.5

Rails is frequently installed locally for other versions using this method, since some applications require a different version of Rails than the global Rails version. You can see what version of Rails might be required by an application by using this command:

# grep -i rails_version /home/username/rails_apps/appname/config/environment.rb

Here username is the cPanel username and appname is the application name. On my machine, here is an example:

# grep -i rails_gem /home/admin/rails_apps/library/config/environment.rb
RAILS_GEM_VERSION = '2.3.4' unless defined? RAILS_GEM_VERSION

To install that older Rails version, you would then use inside the application’s folder:

# cd /home/admin/rails_apps/library
# gem install rails -v=2.3.4

3. Gem mkmf.log location
When a gem will not install, it will produce a mkmf.log file and that entry will appear in the gem install failure message. For example, RMagick gem failing:

# gem install rmagick
Building native extensions.  This could take a while...
ERROR:  Error installing rmagick:
    ERROR: Failed to build gem native extension.
/usr/bin/ruby extconf.rb
checking for Ruby version >= 1.8.5... yes
checking for gcc... yes
checking for Magick-config... yes
checking for ImageMagick version >= 6.4.9... no
Can't install RMagick 2.13.1. You must have ImageMagick 6.4.9 or later.
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of
necessary libraries and/or headers.  Check the mkmf.log file for more
details.  You may need configuration options.
Provided configuration options:
Gem files will remain installed in /usr/lib/ruby/gems/1.8/gems/rmagick-2.13.1 for inspection.

Results logged to /usr/lib/ruby/gems/1.8/gems/rmagick-2.13.1/ext/RMagick/gem_make.out

So, can also check log file:

# cat /usr/lib/ruby/gems/1.8/gems/rmagick-2.13.1/ext/RMagick/mkmf.log
checking for Ruby version >= 1.8.5... -------------------- yes
find_executable: checking for gcc... -------------------- yes
find_executable: checking for Magick-config... -------------------- yes
checking for ImageMagick version >= 6.4.9... -------------------- no
Can't install RMagick 2.13.1. You must have ImageMagick 6.4.9 or later.
System needs ImageMagick 6.4.9 or later.

You can then check the version we install:

# convert --version
Version: ImageMagick 6.4.8 2010-10-14 Q16
Copyright: Copyright (C) 1999-2009 ImageMagick Studio LLC

In this instance, to install the gem, you would need to configure ImageMagick from source to get the higher version required:

# cd /usr/src
# wget
# tar xvfz ImageMagick.tar.gz
# cd ImageMagick*
# ./configure
# make
# make install

4. Gem error for ri and RDoc documentation
These errors are non-fatal and only pertain to documentation. They are meaningless to the gem working.

For example, you might see the following on installing mysql gem:

# gem install mysql
Building native extensions.  This could take a while...
Successfully installed mysql-2.8.1
1 gem installed
Installing ri documentation for mysql-2.8.1...
No definition for next_result
No definition for field_name
No definition for field_table
No definition for field_def
Installing RDoc documentation for mysql-2.8.1...
No definition for next_result
No definition for field_name
No definition for field_table
No definition for field_def

What matters here are these lines:

Successfully installed mysql-2.8.1
1 gem installed

This means the gem did successfully install. Documentation, while important, doesn’t impact a gem functioning.

5. Gem won’t install on system due to stdio.h failure
On trying to install a gem, the following type of error occurs:

ERROR: Error installing hpricot:
ERROR: Failed to build gem native extension.
/usr/bin/ruby extconf.rb
checking for stdio.h... no
*** extconf.rb failed ***

Check /usr/bin/ld and /usr/bin/gcc for file permissions. They both must be 755 for gems to install.

If instead the user is unable to install a gem, check if they have compiler access:

WHM >> Security Center >> Compiler Access

If they do not, they cannot compile some gems. The user can either enable compiler access or install the gem using WHM or root SSH.

Mongrel Specific Tips
Stopping mongrel process and using regular Rails process for checking errors. You would change to the user’s application directory, ps aux that user’s mongrel process, kill the process, then start up the application manually.

# cd /home/username/rails_apps/appname
# ps aux | grep mongrel | grep username
# kill -9 pid#
# ruby script/server -p port# -d

In the above, please replace username with the cPanel username, appname with the application folder name, pid# with the PID number for the mongrel process, and port# with the port number that the application is using (again, you could either have seen this in the ps aux for the mongrel process before killing it or in cPanel > Ruby on Rails area by hovering over the URL link for the application). When you restart the application without mongrel, you will then get errors mongrel won’t provide such as this example:

# ruby script/server -p 12008 -d
Missing the Rails 2.3.5 gem. Please `gem install -v=2.3.5 rails`, update your
RAILS_GEM_VERSION setting in config/environment.rb for the Rails version
you do have installed, or comment out RAILS_GEM_VERSION to use the latest
version installed.

This indicated that Rails 2.3.5 is required, so you would install it onto the account itself:

# gem install -v=2.3.5 rails

Then it should start via command line:

# ruby script/server -p 12008 -d
=> Booting Mongrel
=> Rails 2.3.5 application starting on

You must be in the user’s application folder to run the “ruby script/server -p port# -d” command.

Of note, if you use this command rather than running it via mongrel process, then you will see errors in a browser once the application starts up if there are still coding issues. Mongrel will hide the errors and put them into the /home/username/rails_apps/appname/log/mongrel.log file. Instead, under mongrel, you’ll see this in a browser:

--Begin error--
We're sorry, but something went wrong.
We've been notified about this issue and we'll take a look at it shortly.
--End error--

Finally, after getting the application working, you can then kill the process started for that port and start the application using cPanel > Ruby on Rails area to get the normal mongrel process running. The mongrel process could also be started in command line using this syntax:

# /usr/bin/ruby -I /usr/bin/mongrel_rails start -p port# -d -e production -P log/

Change port# to the port number for the user. Change production to development if the user is under development environment instead.

Important Folder Locations
/home/username/rails_apps/appname/public ==> Location for the public files, this is what we show in a browser
/home/username/rails_apps/appname/config ==> This folder contains the database.yml and environment.rb files. The database.yml file configures the database for the rails application (such as mysql or sqlite or postgres, the database name, database username and password). The environment.rb file can set the rails gem version to use.
/home/username/rails_apps/appname/log ==> This folder contains the log files
/home/username/rails_apps/appname/app ==> This folder contains the main coding for the application with folders controllers, helpers, models and views inside of it.

Of note, the older cPanel Rails applications were installed to /home/username/etc/rails_apps/appname instead. If you cannot find the Rails application at the current path, check in /home/username/etc instead.


- Posted by Tristan James Wallace

This entry was posted in Product Development. Bookmark the permalink.
  • No one

    what is the current version of ruby on rails available on cpanel?

  • Yulian Sutopo

    yum install ImageMagick-devel

    will solve problem in rhel and centos for rmagick