How to deploy a Rails application on HostingRails.com

This is a wiki article created by HostingRails users. Please login or signup to make edits.

This tutorial assumes you are a beginner but have a working Rails app on your local machine ready for deployment onto your HostingRails.com account.  It also assuming you have no interest in deploying via SVN/Git & Capistrano at this time:  

Contents:

1. Receive your welcome email and take note of important info
   
2. Log into your cPanel and set up your mySQL database(s)
   
3. Create online versions of your environment.rb and database.yml files
   
4. Make sure your .htaccess file sends requests to dispatch.fcgi
   
5. Login to the command line and generate your Rails app
   
6. Upload only key folders and files to your online app
   
7. Make your app's public folder the public_html
   
8. And that's it, your app is live!  Let's take a sneak peak
   
9. Note: Making changes to your app when its in production mode
   
10. Note: Answers to common problems
    

---

Receive your welcome email and take note of important info

1. The IP address of your account - xx.xxx.xxx.xxx
   
2. Your username and password
   
3. The link to your cPANEL - i.e. https://xx.xxx.xxx.xxx:2083
   

---

Log into your cPanel and set up your mySQL database(s)

1. Create your database
   
2. Create a user
   
3. Assign that user to the database (if you forget this step a database-driven app will fail)
   

Note that your database name and username will have your HostingRails.com account name as a prefix (e.g jimmy_databasename, jimmy_username, etc...) - this is important for your database.yml file.

---

Dump your local machine database data into the new database you just created.
Back to top

• Via phpMyAdmin?  You can click on the phpMyAdmin link at the bottom of the cPanel mySQL page.
  
• Via Command line?  Backup your database to a *.sql file, upload it to your app's db folder, then:

  [~/yourapp]# mysql --user=hruser_dbuser --pass=*** hruser_dbname < db/your_schema.sql    
  

  or simply do a

  rake db:migrate RAILS_ENV='production'

---

Create "online versions" of your environment.rb and database.yml files
Back to top

Though every developer has their own method for keeping track of their local app config vs. online app config - one might recommend simply creating "environment.rb.online" and "database.yml.online" files that you'll use to upload (and then erase the .online part to replace the existing online files, of course.)

Your database.yml(.online) file simply needs to look like this:

production:
  adapter: mysql
  database: [your_hostingrails_username]_[your_database_name]
  username: [your_hostingrails_username]_[your_database_username]
  password: your_password

(Yes you can erase all the other stuff - this is all you need. Never run in development mode online with HostingRails.com or any shared server)

And in your environment.rb(.online) file you'll just need to find the following line and uncomment it to confirm you're in production mode:

ENV['RAILS_ENV'] ||= 'production'

NOTE: if you don't see this line, and are running Rails 2.3.2, add the following line above the line that sets RAILS_GEM_VERSION:

RAILS_ENV = 'production'

---

Make sure your .htaccess file sends requests to dispatch.fcgi
Back to top

Please Note - as of Rails 2.1.0, the .htaccess file is no longer generated when you create a Rails application.  If you don't have one on your machine, SSH to your server account, run

rails  _2.0.2_  tempapp

and move tempapp/public/.htaccess, dispatch.fcgi, dispatch.rb and dispatch.cgi over to your application directory

This one is easy but also critically important. In your local Rails application's public/.htaccess file change the

RewriteRule ^(.*)$ dispatch.cgi [QSA,L]

(EXACTLY where it is already in the file, don't change its position) to:  

RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

also - very important make sure the 'AddHandler fastcgi-script .fcgi' is commented out at the top of your .htaccess:

# General Apache options
# AddHandler fastcgi-script .fcgi

---

Note: many people run into problems at this point because they upload their dispatchers from their local box which often has a different Shebang (the first line of the file that starts with #!) than what is needed. This prevents dispatch.fcgi from running. To avoid this problem, generate your rails app on the server itself (which we'll do next) and leave the dispatch.fcgi file alone.

---

Login to the command line and generate your Rails app
Back to top

     Using your favorite SSH client (for a free Windows client - try PuTTY), connect to your IP and stay at your user root directory (which is /home/username/ ) and:

[~]# rails your_app_name

Let the Ruby on Rails magic happen and you'll then be able to see your online folders - which we'll upload files to next...

---

Upload only key folders and files to your online app

     OK, your skeleton app should be located now at your root ([~]) - you'll now want to move over the following folders and/or files (if you're using Firefox, consider using their FireFTP to perform the transfer, it will help make life easier):

• whole app folder (yeah, with the controllers, models, helpers, views)
  
• public/images
  
• public/javascripts
  
• public/stylesheets
  
• public/.htaccess (with the dispatch.fcgi rewrite)
  
• db/migrate (but not schema.rb)
  
• config/database.yml(.online, if you did this above, then remove the .online part)
  
• config/environment.rb(.online, if you did this above, then remove the .online part)
  
• (we'll do routes.rb later, hold on)
  
• Also add any libs, scripts, environments, etc...that you might need (you know your app), if you need a specific gem installed that is not already use this tutorial.
  

---

Make your app's public folder the public_html
Back to top

(so domain.com will point to your app)

Ok first, if you haven't already done so, in your routes.rb (under the config directory) set the root route to the name of your main controller.

For Rails apps developed prior to 2.0, uncomment the following line and add in your controller name):

map.connect '', :controller => "your_main_controller_name"

For Rails 2.0+ apps, uncomment this line instead and substitute you  "your_main_controller_name" for "welcome":

# map.root :controller => "welcome"

Then upload this routes.rb file into your online config/ folder.

Next, You must delete the index.html in your public/ folder.

Finally, let's create the symbolic link ("symlink") so the www directory is your Rails app public folder. Get to your root directory and:

[~]# mv ~/public_html ~/public_html_backup
[~]# ln -s ~/yourapp/public ~/public_html

---

The Sneak Peak
Back to top

By now, you've set your nameservers to those designated in your welcome email, but if you can't wait for all the routers to find your new address you can take a sneak peak.  The url for your 'Sneak Peek' domain was also sent in your Welcome email and will point at your main app symlinked at public_html. If you need a sneak peek to test a subdmain app, you can always request one from support@hostingrails.com.

---

Note: Making changes to your app when it's in production mode
Back to top

In production mode with FastCGI much of your application data is cached and held in memory. This means that Rails is 'always on' and ready to feed a browser with code - which makes Rails fast. However, if you make any changes to your app (database, controllers, views, models, config, etc...) and don't see your changes right away, you'll need to run via the command line:

[~]# killall dispatch.fcgi

You'll see that you won't be able to shut down other users' processes (thankfully), but unless you see a "no processes killed" this means your dispatch.fcgi processes were indeed killed and ready to start up again with the new changes incorporated.
Or you can run the following command

[~]#pkill -9 -u <your_username_here> dispatch.fcgi

---

Note: Answers to common problems
Back to top

Not working?

Well - there's not much worse than going through a tutorial and having it not work. You're probably either getting an Application Error (Rails) or a 500/404 error (which means Rails didn't even fire up). In the former case, you can make your way to your app's log/production.log and see what's going on - and in the latter you can make your way into your cPANEL error log page and see if that tells you anything.  Also, sometimes, running the app (temporarily) in development mode can generate more information in the development log.

However, the most common problems are that people upload their whole public folder (rendering the shebang line problem), they don't have their database settings correct in the database.yml (this would get picked up in the logs), they need a gem or lib installed, the online database data/settings doesn't match their local database (again, picked up in production log), their permissions got messed up somewhere along the way (e.g. make sure your dispatchers are CHMOD 755) or they had a typo somewhere (where again, the logs are helpful!). There are other reasons why deployment can fail, so please feel free to check out this thread or ask a question in the forums." "