Prerequisites

• A working UltraScan III system. Either download an installer appropriate for your system at ​http://www.ultrascan3.uthscsa.edu/download.php or download the ​source code and follow the ​build instructions.
• A database/LIMS III system. Either request a new instance on our server for your institution at ​http://uslims3.uthscsa.edu/uslims3_newlims/request_new_instance.php or set up your own server using ​these instructions.

Setting up Grid Control

• Check out the grid control program. Ideally one would set up a new non-root user for this purpose. Create the gfac database:

mysql> CREATE DATABASE gfac;
       exit;

$ mysql -u root -p gfac <gfac.sql

• In the bin directory, copy the config template file to listen-config.php. Fill in all the appropriate information. Many of the variables contain the same information as in the LIMS config.php file, and these should match. Make sure the section called "US3 DB credentials" contains a user that can access any of the LIMS databases, and can use standard SQL queries.
• Open a port to listen for UDP messages.
• Create the socket file and the various log files used by the system. UDP messages queue through the socket file before being picked up by grid control, and the log files are used to record anything out of the ordinary:

$ mkfifo /path/to/us3-pipe
$ touch  /path/to/udp.log
$ touch  /path/to/manage.log

• Start the listen system. This is what listens to the UDP port and dispatches any messages:

$ /usr/bin/php /home/username/bin/listen.php

• If the listen system is running and you want to make changes, you need to stop two programs:

listen.php
manage-us3-pipe.php

• You can send your own messages to the listen system for testing. The format of the message should be "db-requestID: message," where db is the name of the LIMS database, and requestID is the LIMS HPCAnalysisRequestID. Messages include "Starting," "Abort," and "Finished" to indicate changes in job status, but they can also include arbitrary text. Take care to include a colon (:) followed by a space. If your system is working messages should be placed in the queue_messages table and ultimately find their way into the appropriate LIMS database and the common data directory.

$ /usr/bin/php gram.php db-requestID: message

• The Grid Control program itself is run as a cron script. It calls cleanup.php as needed.

cd /home/user/bin/; /usr/bin/php /home/user/bin/gridctl.php

• Another program run as a cron script is the cluster status program. It updates the usage information on supported clusters so that the user can make a better decision about which cluster to select for the job:

cd /home/user/bin/; /usr/bin/php /home/user/bin/cluster_status.php

• Finally, in production the common data directory will fill up with previously-run jobs. It is useful to keep this information for a period of time, but then to consider deleting directories more than a certain age. A cron script is useful for this too.