INSTALL.txt

Installing CatTrack
-------------------

This document assumes you know how to install a standard rails
application and only documents the features that are unique to
the CatTrack application.

We're using Capistrano to manage the deployment of the cattrack
application to the production machines. The default configuration
files can be used to setup a mongrel_cluster fronted by an apache
proxy load balancer. Some hints below.

Database Setup
--------------

1. Copy "config/database.example.yml" to "config/database.yml" and edit
   the database settings for production environment.
2. Run "rake db:migrate RAILS_ENV=production" to initialize the database
   structure and populate it with required values.
3. Run "script/console production" and create a user that will have
   access to the administration section of CatTrack. Simple transcript
   follows;

 > u = User.new
 > u.username = 'myusername'
 > u.password = 'mypass'
 > u.active = true
 > u.admin = true
 > u.save!

SystemSettings and Local Configuration
--------------------------------------

1. Copy "config/local.example.rb" to "config/local.rb" and edit the mail
   settings.

2. Customize SystemSettings.  
   Run "script/console production" and make the following changes:
 a) email
   > SystemSetting['mail.from'] = 'rvm-regression@cs.anu.edu.au'
   > SystemSetting['mail.on.error'] = 'cattrack.admin@example.com'
   > SystemSetting['report.mail.to'] = 'jikesrvm-regression@lists.sourceforge.net'
   > SystemSetting['report.reply.to'] = 'jikesrvm-core@lists.sourceforge.net'
 b) installation/project customization
   > SystemSetting['installation_name'] = 'a pretty name of your installation'
   > SystemSetting['scm.url'] = 'base URL for ViewVC for your project'

Web Setup
---------

1. If you are not hosting cattrack at the root level of your web application
   then you will need to edit "config/local.rb" so that contains code such as

   ActionController::AbstractRequest.relative_url_root = "/cattrack"

2. You will need to edit config/deploy.rb to tell it basic facts about your setup.
   Other configuration files should be usable without change as long as you deploy the
   application to /home/cattrack/cattrack.  If you want to put it somewhere else, then
   you will need to edit additional configuration files.

3. You will need to configure apache and possibly the mongrel cluster.  There is a snippet
   of an httpd.conf file in /etc that can be used as a template.  You will need to do OS
   level configuration to make the mongrel-cluster into an init.d service. 

Cron Setup
----------

1. There is a sample crontab in etc.  At a minimum the crontab should be flushing 
stale sessions and running the import jobs. You may want to restart the mongrel_cluster
as well.

Misc Setup
----------

1. If your system uses logrotate, there is a sample conf file in etc.

Capistrano Hints
----------------

config/deploy.rb is written to support deploying to multiple sets of servers (anu for JikesRVM,
watson for X10).  When invoking cap, you must specify which deployment you are targeting on the 
command line:
  cap -S where=anu <...rest of command...>
or
  cap -S where=watson <...rest of command...>

The most common command is 
  cap -S where=anu deploy
which will deploy a new version of the application.

Documentation for all of the task is available via:
  cap -T -S where=anu