Setting up Rails and Mongrel on cPanel
From OCS Support Wiki
Contents |
[edit] Introduction
This guide will show you how to create a Ruby on Rails application and Mongrel instance (complete with assigned Mongrel port) in cPanel, and how to manage your application.
[edit] Logging into cPanel
To begin, you will need to gain access to your cPanel interface. You can do this by going to yoursite.com/cpanel, or follow the link in your control panel.
[edit] Ruby on Rails Application Section
Once you're in cPanel, click the Ruby on Rails icon that looks like this:
Once inside, you'll see a screen where you can install and manage your Ruby on Rails applications.
[edit] Creating a Ruby on Rails / Mongrel Instance
Even if you already have developed your Rails app, you will need cPanel to generate the skeleton of it again and configure Mongrel for you. To do this, enter the information requested in the creation form, as shown below.
We recommend you use a folder called rails_apps and place your app in it. cPanel will default to a folder in the public_html area, but this is not recommended as your code will be visible to everyone. In the example above, our application is called myapp and the path to the folder it is in would be rails_apps/myapp. This keeps your code out of the public view.
Make sure "production" mode is set (we don't allow running Mongrels in development mode) and click "Create". Your app will be created for you.
[edit] Uploading or Deploying an Existing Rails App
This is the ideal time to upload via FTP, checkout via Subversion (recommended), or deploy with Capistrano your application to the folder you just created. Before you do this, we recommend clearing out the folder, ridding it of the Rails instance that was just created by cPanel, although this step isn't absolutely necessary.
[edit] Deploying via Subversion
If your application lives in a Subversion repository, simply go to the directory that you've setup your Rails instance in via SSH and check it out, like this:
cd ~/rails_apps/myapp svn co http://svn.yoursite.com/path/to/myapp/trunk .
This will check out your app from a Subversion repository. If you don't have a Subversion repository yet, we recommend creating one with us. Simply see Request_a_Subversion_and_Trac_Account.
Even if you plan to deploy with Capistrano later on, it's usually a good idea to do your first checkout via Subversion. This way your Subversion login credentials will be cached.
[edit] Migrations
Once your application is in the ~/rails_apps/myapp folder (replace myapp with the name of your app), make sure you're in that folder via SSH and run:
RAILS_ENV=production rake db:migrate
If you haven't used migrations or need to copy an existing live database, you can either use the graphical tools in cPanel (such as phpMyAdmin) or you can review our guide on Importing_and_Exporting_MySQL_Databases.
[edit] Starting Your Mongrel
Once you've got your existing app in the folder that cPanel made for your Ruby on Rails application, click the green start button in the Ruby on Rails management section of cPanel. This will start your app. You can click on the URL link to see your application via a temporary URL. You can also stop the application and set it to start upon server boot in this section as well.
[edit] Redirecting Your Website to the Mongrel
Please see Redirecting_Website_to_Rails_App_on_cPanel.
[edit] Troubleshooting
If you run into problems starting your Mongrel, check the log/production.log file in your Rails application folder. It will generally give a clue as to the problem.
Also, you can connect via SSH and change to your Rails application directory and try and launch the console:
cd ~/rails_apps/myapp RAILS_ENV=production ruby script/console
This will generate errors, usually the same ones that a failed Mongrel start will produce that will help you troubleshoot the issue.
[edit] Common Problems
[edit] Database Not Setup
If you see errors related to MySQL, it typically means that either your database isn't created or populated with the tables your app needs to function. Please see the section above about migrating your data.
[edit] Missing Gem
If your Rails app is looking for a gem that isn't installed, we may need to install it on our servers. Please contact us to let us know.
[edit] Incorrect Rails Version
If you are using a version of Rails that isn't on our server, you might get some strange issues. We always recommend freezing Rails to your application. Alternatively, you can adjust config/environment.rb and change the Rails version to what you need (1.1.6, 1.2.6, and 2.0.1 are common varieties).
[edit] Redirecting Your Site to the Rails App
Once you're satisfied with the functionality of your application, you can use the "Create a Rewrite" section in the Ruby on Rails management section of cPanel to direct your whole website (or a certain folder in the site) to the application. If you want to direct your entire site, leave the portion after your domain name blank. If you want to put it in a sub folder, put the name of that folder in the field.
