How to Setup a Rails application in cPanel

Setting up a Rails application should be painless, but there are times when some hosting restrictions make deployment a real pain in the ass. I would like to share with you some tips that hopefully will help you get over some of the obstacles in deploying a Rails application using cPanel.

Currently my hosting provider does not provide shell access to my account. As we all know, shell access can spell the difference between a good dream and a nightmare deployment.

As a note, all of this was done using cPanel 11.24.5-RELEASE.

Step 1: Create your application in your local machine or from any source

Its as simple as running rails my_app, then populating the code with whatever you want it to be.

Step 2: Check the Rails gems in cPanel

Make sure that the Rails version on cPanel is the same as the version used in your application:

1. Login to your cPanel administration panel. e.g. http://myapp.com/cpanel
2. Enter your username and password
3. Under Software and Services, click RubyGems

cPanel is using the latest available Rails gems. If your application is created using an earlier Rails version, you will need to "vendor" the older version of Rails (as described later in the post).

Step 3: Create the Rails application directory using cPanel

1. Login to your cPanel administration panel. e.g. http://myapp.com/cpanel
2. Enter your username and password
3. Under Software and Services, click Ruby on Rails
   
4. Enter your application name under App Name
5. Check Load on Boot (I haven't tested this yet, but some sources say that this is not working, but check it anyway)
6. The Application Path will be automatically updated using your application name. Take note that your Rails application is now residing under /home/<user>/etc and not in /home/<user>/public_html. This was probably due to security reasons to make your code inaccessible to prying eyes.
7. Set the Environment to production mode
8. Create! cPanel will automatically generate all the necessary files and folders needed by your application

Step 4: Vendor your ruby gems

Vendoring gems means putting the gems used by your application in the vendor/gems directory. This will ensure that your application will still run smoothly even if the system-installed gems in the server is changed. To properly do this, follow these steps:

1. In your local machine, make sure the gem you will vendor is currently installed. If not, run
gem install <gem name>
2. Put the proper config.gem in config/environment.rb for each gem you will use
3. Unpack the gems to be used  in  into the vendor/gems directory using this command:
   rake gems:unpack
4. Check each unpacked gem if it contains a .specification file.

Example: Vendoring the sqlite3 gem

In my case, the sqlite3 gem is not included in the system-installed gems. Since I will be using sqlite3 and not mySQL as my database, I need to vendor it.

1. In your local machine, install the sqlite3 gem (if it is not installed yet)
   gem install sqlite3-ruby
2. Uncomment the config for the sqlite3 gem in config/environment.rb
config.gem "sqlite3-ruby", :lib => "sqlite3"
3. Run rake gems:unpack

Step 5: Populate your application with your code

Its now time to upload your code into cPanel. There are many ways to do this, but what I did was to upload my code using FTP and then moving the uploaded code into the main application under /home/<user>/etc/rails_apps/myapp

You will need to upload the following folders: app, vendor, db, config, lib, and public

Warning!
If your application uses Rails plugins, the vendor directory may contain thousands of files, making uploading it very slow. To solve this, I highly recommend archiving/compressing the directory first. Use gzip to compress the archived file. Do not use other types of compression (e.g. zip, rar) since they are not recognized by the cPanel Extract command!

To archive and compress a directory (for example, the vendor directory):
tar -cf vendor.tar <path of folder>/vendor
gzip vendor.tar

After compressing, upload the *.tar.gz file into cPanel. When the upload is finished, go to the cPanel File Manager. Navigate to the folder where you uploaded the file, check the *.tar.gz file and then press the Extract button on the top menu. Enter the directory where you want it to be extracted, and then press Extract. A window showing the files being extracted must be displayed. If the only thing you see is a loading bar saying that the file is being extracted, then the compression type you used is not recognized by cPanel.

After extracting the file, copy/move its contents to the main application directory in /home/<user>/etc/rails_apps/myapp

Step 6: Run your application!

It is now time to test your application. cPanel provides a simple method of stopping or starting your Rails application. Just go to Software and Services, click Ruby on Rails and click either the Run or Stop buttons to start or stop the mongrel processes. There are some things to remember though!

1. Make sure you deleted/renamed the default Rails index page located at:
   /home/<user>/etc/rails_apps/<myapp>/public/index.html
2. Check the log files if your application refuses to run. The log files are located at:
   /home/<user>/etc/rails_apps/<myapp>/log/mongrel.log
/home/<user>/etc/rails_apps/<myapp>/log/production.log
3. Do not delete the mongrel process id (pid) file! This file is needed by cPanel to determine which processes to stop when you need to stop your Rails application. I accidentally deleted this one time, and because of it I was unable to restart my application and I needed to contact the system administrator to manually kill the mongrel process (since I do not have shell access). This file is located at (why do they put it there...):
   /home/<user>/etc/rails_apps/<myapp>/log/mongrel.pid

Step 7: Create a Rewrite

Your Rails application is now running at a different port than your main URL. For example, the Rails application running in marvspace is at http://marvspace.com:12001. What you want is to make your main URL to point to this specific port. To do this, you need to create a Rewrite in your site public_html/.htaccess file to redirect all requests from your main URL to your Rails application running at a different port.

Fortunately, cPanel provides a very easy way to create a Rewrite. All you need to do is go to Software and Services, click Ruby on Rails and click Create a Rewrite beside the application name. If you check your .htaccess file, you will see these lines:

RewriteEngine on
Options All -Indexes
RewriteCond %{HTTP_HOST} ^marvspace.com$ [OR]
RewriteCond %{HTTP_HOST} ^www.marvspace.com$
RewriteRule ^/?$ "http\:\/\/127\.0\.0\.1\:12001%{REQUEST_URI}" [P,QSA,L]

To put it into plain words, these lines mean: "If a request starting with marvspace.com or www.marvspace.com is accessed, that request is to be handled by the application running at port 12001."

Step 8: Got Errors?

Sometimes your Rails app refuses to run even if you already checked the above things. I will share to you some of the problems I encountered and how to solve them.

Error: My Rails app wont start and the production logs do not show anything.
Solution: Restart your application in development mode. View the development.log file to see the actual cause of error.

Error: no such file to load -- sqlite3
Solution: The sqlite3 gem is not installed in the system. Follow the example at Step 4 to install the sqlite3 gem

Error: libsqlite3.so: cannot open shared object file: No such file or directory
Solution: The system does not have the shared object file required by sqlite3. To solve this, you need to put the  libsqlite3.so file directly into your filesystem.

1. Download the libsqlite3.so file here.
2. Put this file into any accessible directory. In my case I put it in /home/<user>/bin
3. Edit the sqlite3 gem to include the uploaded libsqlite3.so file.
   In /vendor/gems/sqlite3-ruby-1.2.4/lib/sqlite3/driver/dl/api.rb


module SQLite3 ; module Driver; module DL;
  module API
    extend ::DL::Importable
    library_name = case RUBY_PLATFORM.downcase
      when /darwin/
        "libsqlite3.dylib"
      when /linux/, /freebsd|netbsd|openbsd|dragonfly/, /solaris/
        "/home/<user>/bin/libsqlite3.so"
      when /win32/
        "sqlite3.dll"

Restart your application for your changes to take effect.

Error: My Rails application started but there are no images or the stylesheet is not loaded.
Solution: The Rewrite generated by cPanel is faulty. To fix this, you need to edit this file and update the Rewrite rule:
/home/<user>/public_html/.htaccess

Open the .htaccess in your text editor and change
RewriteRule ^/?$
to
RewriteRule ^.*$

Error: I edited my .htaccess file and now my files and folders under public_html are now inaccessible via URL
Solution: Since the updated Rewrite basically says that all requests be redirected to the Rails application, the URLs your other non-Rails directories are now being routed to the Rails application, causing an error. To circumvent this, either edit again the .htaccess file to exclude certain requests or use subdomains.