How to setup a new computer to run regression jobs on the Artifex Cluster:

0.  Make sure you have the correct packages installed to be able to
    compile Ghostscript, GhostPDL, and GhostXPS.  For a standard 
    Ubuntu 10.04 installation you need the following additional packages:

      subversion
      autoconf
      g++
      libx11-dev
      libxt-dev
      libxext-dev
      libcups2-dev
      libcupsimage2-dev

1.  Setup limited access passwordless ssh to the regression server:

    Copy the cluster_key file to your ~/.ssh directory (you can find this file
    on casper in /home/regression/cluster_key).

    Change the permission of this file is 600.

    Choose a name for your cluster node.  This does not have to match
    the hostname but does have to be unique within the cluster (check
    the dashboard at http://ghostscript.com/regression/index.html for
    a list of the current cluster node names).

    Inform Marcos of the name so that he can add it to the list of
    machines allowed to send commands to the server (which involves
    editing the file /home/regression/.ssh/authprogs.conf on casper).

    After Marcos lets you know that your machine has been added you
    should be able to to run a very limited set of commands via ssh
    using the cluster_key without being asking for your password.
    To test this try (replacing your_machine_name with your previously
    chosen machine name):

      ssh -i ~/.ssh/cluster_key regression@casper.ghostscript.com \
        touch /home/regression/cluster/your_machine_name.done

    You can verify that an arbitrary command is not allowed by trying:

      ssh -i ~/.ssh/cluster_key regression@casper.ghostscript.com \
        touch /home/regression/cluster/your_machine_name.test

2.  Make a directory where the cluster software can live, the
    location on the other nodes is ~/cluster but it can be anywhere
    you like.

3.  Checkout the various test files and source code by executing the
    setup_cluster script.  You may already have copies of these files
    on your machine but I'd rather not support having them installed in
    other directories, so please just live with another copy.

    Note that this will take a while (2+ hours), though the time will
    vary based on what else casper is doing at the time and your
    internet connection speed.

4.  Test to make sure that your system can compile Ghostscript and the
    other languages using the same configuration that the cluster uses:

    cd ghostpdl/gs
    ./autogen.sh "CC=gcc -m64" --disable-fontconfig \
      --without-system-libtiff --prefix=/tmp/gs
    make
    make install
    /tmp/gs/bin/gs -o test.ppm -sDEVICE=cups ./examples/tiger.eps 
    cd ../..

    cd ghostpdl
    make pcl "CC=gcc -m64" "CCLD=gcc -m64" 
    main/obj/pcl6 -h
    make xps "CC=gcc -m64" "CCLD=gcc -m64" 
    xps/obj/gxps -h
    cd ..

5.  Copy the clusterpull.sh script from the
    ghostpdl/gs/toolbin/localcluster directory and change it by editing
    the line:

      set machine=REPLACE_WITH_YOUR_MACHINE_NAME

6.  Add the following to your crontab, this schedules the clusterpull.sh
    script run once every minute (you'll have to appropriately change
    user_name and possibly the directory name):

    * * * * * cd /home/user_name/cluster ; ./clusterpull.sh

    Note that the clusterpull.sh script is fairly low impact; once a
    minute it sends a heartbeat signal to casper via 'ssh touch' and
    checks to see if a job is ready to run by attempting to scp a file
    from casper.

7.  Viola!  Sit back, relax, and watch your cpu load climb to the roof
    the next time someone does a commit.

    You don't need to keep your machine up 24/7, since if a node hasn't
    sent a heartbeat in a while (currently defined to be three minutes)
    it is assumed that machine is down and it won't be assigned any
    cluster jobs.

    Similarly you can shutdown/reboot your machine without concern that
    it's currently running any cluster tasks since when a machine goes
    down during a cluster run the jobs that it has already completed
    will be assigned to the remaining nodes (under rare circurmstacnes
    (i.e. if all of the other nodes are already finished when the final
    node goes down) the cluster job will be restarted from scratch).

    If you want to temporarily disable your machine from participating
    as a cluster node touch the file clusterpull.lock in the directory
    where you installed the cluster sofware (~/cluster by default).
    Your machine will be automatically renabled as a cluster node in
    two hours.

    You can force the removal of your machine as a node during a cluster
    run by removing the file run.pid in the directory where you installed
    the cluster sofware (~/cluster by default).


