Using Ruby On Rails on Bluehost:

This is intended to be a brief introduction to developing ruby on rails applications on a account with us.
At the bottom of this article you will find a number of resources to help you learn more about ruby on rails and related information, as well as links to some rails tutorials that will go into more depth than this document.
Before you start digging your feet into Ruby on Rails, you should understand exactly what it is.
Ruby on Rails is an advanced object-oriented Model-View-Controller application framework. If you didn't fully understand the meaning of the previous sentence, you're going to need to put in some study time before you can jump into rails programming. Ruby On Rails is aimed at advanced programmers; jumping into it before you're ready is likely to be very very hard. This tutorial should be easy enough for anyone to follow, but there's a lot more to rails than you'll be learning here.

This tutorial serves as a first step into ruby on rails development on Bluehost. The Model-View-Controller (abbreviated to MVC) design pattern is fairly straight-forward, it simply means that your program is split into three separate components: The Model, View, and Controller. The "Model" is your data, no matter how it's stored. If you're writing a blog, this is where all of your posts and comments would go. The "View" is your interface. In the case of ruby on rails, we're talking about the part that displays your HTML. The controller handles the business logic, and ties the model to the view. MVC programming is beneficial for many reasons. From this point on it is assumed that you have an understanding of both object-oriented design and MVC, and now you can get into how to develop rails applications on Bluehost.

A few additional notes before you start: First of all, you need to have SSH access enabled.

Secondly, you'll see a lot of tutorials referring to a program called "script/server" or "webrick". This is NOT NECESSARY on a Bluehost account, and you should never have to use it. This is designed for people who are developing their rails application on their own computer where there is no apache install which is pre-configured to use ruby on rails.
However, you do have access to such a server on Bluehost, so you do not need to worry about script/server. Do not run it, as it is not set up to work properly.

Third, this tutorial assumes that you are using MySQL.

This document is Bluehost-specific. To begin, log into the server using SSH. You'll need a work area for your rails application. Assuming ahead of time that you may eventually want multiple applications, you should make a work directory and then cd into it. You can name it whatever you would like, but this document assumes that it is called "rails".

  % mkdir ~/rails
  % cd ~/rails   

Now you may create your application. As we are just making a simple Hello World application, we'll assume that the application is named "first".  How you create the application depends on what version of Rails is on your server (currently we are in the process of upgrading all of the servers to 2.3.2, but while this is not complete some servers may still be running 2.2.2).  To find out which version of rails you are running use the following command:

  % rails -v

If you are running rails 2.3.2 then you will need to create your application like this:

  % rails -D -d mysql first

The -D is short form for "--with-dispatchers".  This is now required for rails 2.3.2 since the dispatch files are no longer created by default.

If you are running rails 2.2.2 then you will need to create it like this:

  % rails -d mysql first

  % cd first  

Next, we're going to set up a subdomain for this application to run on.

Log into your cPanel, click on 'subdomains', then type 'first' into the first text box and click 'Add'. You've now created a new subdomain, first.yourdomain.com, which will be the new home of your ruby on rails application. Now, we're going to make your application's "public" directory be the rootdir of that subdomain with the following commands:

  % cd ~/public_html/
  % rm -r first
  % ln -s $HOME/rails/first/public $HOME/public_html/first   

You should now be able to go to http://first.yourdomain.com/, where you will see the Ruby on Rails welcome message. As the welcome page suggests, it is now time to set up your databases.

In cPanel, click on 'MySQL Databases'. The first thing you'll want to do here is add an SQL user for rails to use. You can name this whatever you'd like. We will assume you used 'rails'. cPanel prepends your username to the user name, so you should take note of the actual name created (it should be username_rails). Next, we're adding a database. Name this database 'first', to match your application name. You will again notice that username_ has been prepended. Since rails supports having a development mode and a production mode we'll also create a second database.  Name this second database firstdev. Finally, we're going to link this username to the database. Select username_rails and username_first from the dropdowns and make sure the 'All' checkbox below them is checked, then click the 'Add User To DB' button. Now you should repeat this step, with 'firstdev' as the database name, and linking username_rails to it.

Now we're going to edit the database.yml file. Open ~/rails/first/config/database.yml in your favorite editor, and modify the 'development' and 'production' sections to contain the username, password, and database that you just created.  You will also want to replace the "socket" line with a line specifying the host:

development:
  adapter: mysql
  encoding: utf8
  database: username_firstdev
  pool: 5
  username: username_rails
  password: password
  host: localhost
  
  
production:
  adapter: mysql
  encoding: utf8
  database: username_first
  pool: 5
  username: username_rails
  password: password
  host: localhost    

At this point the old tutorial directed you to create the model, view, and controller separately.  The tutorial now differs in that it will take a more "rails like" approach.  

We're going to create what's called a "scaffold".  A scaffold with create a CRUD structure for information, the controllers, the views, and the routes necessary for a basic application.

  % cd ~/rails/first
  % ./script/generate scaffold Person name:string street1:string street2:string city:string state:string zip:string
  
This will create everything your basic application needs, but we're not quite done.  You will need to type in one more command:

  % rake db:migrate

This will set up the database for you.

Now that we have this set up we will need to add a way for rails requests to be processed.  We will need to create rewrite rules in a .htaccess file so that all non-static reuqests coming into your application are processed through fastcgi.  

  % touch ~/rails/first/public/.htaccess

Now, edit the newly created file with your favorite editor and add the following:

# General Apache options
AddHandler fcgid-script .fcgi

RewriteEngine On

RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)/!$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

ErrorDocument 500 "<h2>Application error</h2>Application failed to start properly"

That's it.  Now you will be able to view your application that you've just created.

Remember that when a you create a scaffold that it takes on the plural form of the name you gave it.  You will need to access it the following way:
 
  http://first.yourdomain.com/people

You can now create, edit, and delete people (along with their associated records). Congratulations, you've now created your first rails application on Bluehost!

Now, how do we make it so that you don't need to go to first.yourdomain.com/people to see the new application?  Is there a way to make it so that you just need to go to http://first.yourdomain.com for it to show up?  Of course there is!

First, delete the index.html page in your public folder:

  % rm ~/rails/first/public/index.html

Now, we'll have to change the routes for your application.  Open up the ~/rails/first/config/routes.rb file and edit the following line (down around the bottom):

    # map.root :controller => "welcome"

Uncomment it out and change it to point to our controller so that it looks like this:

    map.root :controller => "people"

Now you will be able to go to http://first.yourdomain.com and the application should come up.  

Another important thing to know about rails on shared hosting is that the environment can change.  While Bluehost tries it's very best to notify customers using Ruby on Rails of any updates inevitably somebody will get missed or forget to take the necessary precautions.  To help prevent your application from breaking when updates get done to the server you can "freeze" your application.  This will effectively make your application use the version of rails that it was created with.  The best way to do this with us is to run the following commands:

  % cd ~/rails/first
  % rake rails:freeze:edge RELEASE=2.x.x (changing 2.x.x to the version of rails you created the application with)



You should now go on to read other ruby on rails tutorials. You can find a lot of helpful information at http://wiki.rubyonrails.org/, as well as at http://rubyonrails.org/docs. You should also watch the Ruby On Rails Screencasts, which show you, among other things, how an experienced ruby on rails developer can create a fully functional application in a matter of minutes using ruby on Rails. ADDITIONAL INFORMATION AND TUTORIALS: More information on MVC: http://wiki.rubyonrails.com/rails/pages/UnderstandingMVC Official Ruby On Rails Screencasts. You should watch these: http://media.rubyonrails.org/screencasts Ruby on Rails wiki. The tutorials listed here are quite helpful: http://wiki.rubyonrails.org/ Why's poignant guide to ruby: You will either enjoy this or hate it, but it's a nice intro to the ruby language: http://poignantguide.net/ruby/