Deploying Ruby on Rails applications on the Tapor Server
This page briefly describes the steps needed to create and deploy a Rails app on the Tapor server. It also outlines some of the obstacles I have encountered along the way, and the solutions I have found.
Steps
- ssh into the Tapor server.
- cd into the directory where you want your Rails app to be created.
- Build the Rails app by issuing rails appname on the command line. This will create the default Rails app structure. Replace 'appname' with your application name.
- Create a symbolic link to the Rails public directory ('appname/public') in your account's public_html directory, or wherever public-facing pages are served from. To do this, cd into the public_html directory and issue the command: ln -s ../appname/public appname, where '../appname/public' is the relative path from the public_html directory to the public directory of your Rails app (the TARGET), and where 'appname' is the name of your app (or whatever you want users to see in the address bar of their browser: http://tapor.mcmaster.ca/~youraccount/appname) (the LINK_NAME).
- cd into the public folder of newly created rails directory ('appname/public')
- Edit the (invisible) .htaccess file and add the following line:
# Example:
# Alias /myrailsapp /path/to/myrailsapp/public
# RewriteBase /myrailsapp
RewriteBase /~youraccount/appname # ADD THIS LINE
RewriteRule ^$ index.html [QSA]
This indicates to Apache that requests to
/~youraccount/appname should be redirected to the public directory of your Rails app. This allows Rails routes to work.
- Navigating to http://tapor.mcmaster.ca/~youraccount/appname in a browser should now resolve to the "Welcome Aboard. You're riding the Rails!" default Rails page.
- cd back up into your rails directory. Set the permissions on the tmp directory to 777, and make sure to 'Apply to enclosed items'. This allows the tmp subdirectories to be written to by the app.
- Do the same for the log directory. Set the permissions on the log directory to 777, and make sure to 'Apply to enclosed items'.
- cd into your config directory. Edit your database.yml file to reflect the database, username, and password you are using for this project. Make sure to specify this information for each of the environments in which you will be working (development, test, production).
- Login to mysql and load the database you defined in database.yml for the environment in which you are working.
- Load in your application specific controllers, models, views, helpers, plugins, javascripts, stylesheets, images, migrations, etc. into the appropriate directories in your rails app.
- Set a default route in your rails app in config/routes.rb.
- Delete public/index.html (the default rails index page).
- In config/environment.rb, uncomment the line which sets the environment to Production, if desired.
Obstacles and Solutions
The steps above
should give you a fully functioning Rails app. Unfortunately, the deployment side of Rails is still fairly tricky, and prone to server specific issues, so you may run into one or more problems. A couple that I've had to deal with are outlined below.
Routes won't resolve
Routes to your controllers won't resolve, resulting in a "Routing Error. No route found to match "/main/index" with {:method=>:get}" or similar. To fix this, try adding this line to your
config/environment.rb file:
# Bootstrap the Rails environment, frameworks, and default configuration
require File.join(File.dirname(__FILE__), 'boot')
RAILS_ROOT = '/home/youraccount/appname' # CHANGE THIS LINE TO THE PATH TO YOUR APPLICATION
Rails::Initializer.run do |config|
This should specify to Rails where your application is being served from, and where the routes defined in
config/routes.rb are relative to.
Random Rails errors
Make sure that your Rails Gem Version is appropriate to the current configuration of Rails on the Tapor server. At the time of writing (Feb 28th, 2008) this was gem version 1.2.3, as defined in
config/environment.rb. If you have modified or created this file in your local development environment, this gem version will have been set to your local version, which may not match.
# Specifies gem version of Rails to use when vendor/rails is not present
RAILS_GEM_VERSION = '1.2.3' unless defined? RAILS_GEM_VERSION # MAKE SURE THIS GEM VERSION MATCHES THE CURRENT VERSION OF RAILS RUNNING ON TAPOR
Generic "We're sorry, but something went wrong." error message generated by Rails
This can be caused by a number of issues which are preventing the Rails app from starting correctly. Two things to check initially are that the
tmp/sessions and
log directories are writable by the server (permissions 777 ...or 666?). If these are not writable, the Rails app won't initialize, as everything depends on being able to create a new Ruby session in
tmp/sessions. Once this is possible, the Rails app will either start correctly, or will at least create a session and begin logging errors in
log/development.log. If the latter is the case, refer to the
development.log file to try to narrow down the problem.
Removing symlink in public_html directory deletes contents of appname/public directory!
I did this a few times before realizing what had happened. If you're in the public_html directory of your account, and you want to remove or rename the symlink to your app, make sure to use
unlink symlink_name and to not simply delete the link. If you do, all the contents of your appname/public directory will be deleted except for the
.htaccess file, rendering a
/youraccount/appname/dispatch.cgi not found error in the browser if you try to view your app.
General Suggestions
The process can either be smooth or extremely tedious...usually tedious. My biggest suggestion would be to test changes as you make them, and proceed slowly and iteratively so that you can catch problems on the step which they occur. Trying to deploy a finished app without testing the steps along the way will most likely result in a variety of errors which will be very difficult to narrow down. Good luck!
--
JohnnyRodgers - 27 Feb 2008
