---
=== SYNOPSIS
---

rq is a tool for instantly building simple linux clusters based on the concept
of coordinated shared access to an nfs mounted priority job queue.  the idea is
a simple one: one, or more, nodes take jobs from a priority queue, run them, and
return their status and other information to the queue.  the priority queue
itself is made available to all the 'feeding' nodes by virtue of it being placed
on a globally visible nfs filesystem.

                          -----------
                          | priority |
                          | queue    |
                          -----------
                         /      |     \
                        /       |      \
                       --------nfs-------
                      /         |        \
                     /          |         \
                ----------  ----------  ----------
                | node_a |  | node_b |  | node_c |
                ----------  ----------  ----------

all feeding nodes are equal, idependent, and isolated.  any node capable of
mounting the nfs filesystem may submit to the queue.  so long as the nfs server
and one node are up - the cluster can continute processing jobs.


---
=== EXAMPLE INSTALL
---

download rq-all.tgz from http://raa.ruby-lang.org/project/rq

unpack rq-all.tgz

the packages/ directory will contain ALL packages required to install rq
including ruby[www.ruby-lang.org]

the file install.sh installs ALL required packages for ruby queue into an nfs
mounted directory.  it is a simple script - feel free to read/edit.


installed packages will include:

* ruby
* sqlite
* sqlite-ruby
* arrayfields
* posixlock
* lockfile
* rq

the install.sh procedure is reccomended since

* a common nfs filesystem is required on which to store the queue anyhow

* installing all packages into this common nfs filesystem means no
  software will be installed locally on any node which simplifies
  maintainance and the addition of new nodes to the cluster.

* root privledges are not required for this technique

* this technique implies only two requirements for any node to join the cluster
  * the nfs filesystem is visible to it
  * a single crontab entry has been added

install.sh should/will not run as root so the user running it must have write
permission (or sudo write permission) to the /nfs mounted directory.

following are the steps for an install into the nfs mounted directory named
'/nfs'.  absolutely NO packages or files will be installed outside this hierachy
so simply use 'rm -rf' to un-install.  
  
  tar xvfz rq-all.tgz

  cd rq-all/

  ./install.sh /nfs  

or use

  ./install.sh /nfs sudo

if, and only if, you require sudo privledges in order to write to /nfs/


---
=== EXAMPLE SETUP
---

= path setup

the following instructions assume your PATH has been set appropriately on all
nodes.  your path should be configured to include the bin directory of the nfs
prefix used in the install.  eg:

  export PATH=/nfs/bin/:$PATH

if this has been done correctly the output of

  which rq

should report something like

  /nfs/bin/rq

/nfs being the location you just installed into


= create the queue

you must create/initialize the queue structure.  this should be done one time