Installation manual

Quick install

Ensure Bowtie 1.0 is added to your PATH variable
Download GT-Scan from the GT-Scan downloads website
Extract GT-Scan: tar zxf gt-scan_VERSION.tar.gz
Change into the GT-Scan directory: cd gt-scan_VERSION
Edit config.ini and specify the path to the Bowtie indexed genomes next to ref_genome_dir
You have now successfully installed and configured GT-Scan! However, you may wish to add GT-Scan to the PATH variable for convenience, where GT-SCAN_DIRECTORY is the full path to where you have installed GT-scan:
- For Bash, run: export PATH=$PATH:GT-SCAN_DIRECTORY
- For C Shell, run: setenv PATH $PATH:GT-SCAN_DIRECTORY
You can now run GT-scan on the included FASTA file, input.fa, by running gt-scan.py
Run gt-scan.py -h to view the usage information

Introduction

The GT-Scan web application implements both a front-end and back-end service to provide an interactive, user-friendly experience. The back-end allows GT-Scan job creation through Apache Tomcat and Opal 2. Opal provides SOAP services, which allow API calls from the external services such as the front-end. The front-end extends on the back-end by providing features such as form validation, job history, a detailed status page as well as a consistent user experience. These instructions are generic for Linux, however they should only require minor modifications for Windows or any other system capable of running Java and Python.

Prerequisite software

The command-line and web-server installation both require:

The web-server back-end requires the following, in addition to the above:

The prerequisite sofware for the web.py or Apache frontend are:

Python 2.7

Further prerequisites of the Apache frontend are:

Apache HTTP server
- mod_wsgi

Command-line

Download and extract GT-Scan to a directory on your machine.
Configure the following parameters in config.ini:
- ref_genome_dir - the base directory containing the Bowtie indexed genomes.
Add the directory to PATH with export PATH=$PATH:GT-SCAN_DIRECTORY.
See the manual for detailed information on using GT-Scan, or run gt-scan.py -h from the command-line for a basic overview.

Back-end server

Follow this section and one of the front-end sections to set-up the GT-Scan web-service. This assumes you have a working installation of the GT-Scan command-line tool and have met the above prerequisites.

By default, Opal will 'fork' new jobs. If many jobs are running simultaneously, system performance will suffer greatly. For a production-quality server, it is essential that jobs be queued to avoid overloading system resources. Opal can handle this by using PBS, which supports queuing jobs on multiprocessor systems (computer servers and clusters). See the 'Advanced' section for instructions on setting up Opal with PBS.

Make the following changes to etc/gt-scan_config.xml:
- binaryLocation - specify the location of gt-scan.py.
- If you intend to use the Opal submission form, (i.e. as a web service via e.g. http://localhost:8080/opal2/dashboard?command=serviceList), insert the names of the Bowtie indexed genomes that you have installed under the  line.
We assume below that TOMCAT_DIRECTORY is the full path to your Apache Tomcat install directory and OPAL_DIRECTORY is the full path to your OPAL install directory.
For OPAL 2.5 (and beyond):
- cp etc/gt-scan_config.xml TOMCAT_DIRECTORY/deploy
For OPAL 2.4:
- cp etc/gt-scan_config.xml OPAL_DIRECTORY/configs
  cd OPAL_DIRECTORY
  ant deploy -DserviceName=gt-scan -DappConfig=configs/gt-scan_config.xml
If Tomcat and Opal are installed on your local machine with default settings, the GT-Scan back-end should be available at http://localhost:8080/opal2/ on the 'Dashboard' under the 'List of applications' tab.

Front-end server (web.py)

Follow the instructions in this section to use web.py's internal web server to host the front-end. This is a simple procedure since all Python extensions are included with the GT-Scan source and minimal configuration of the server is required.

Extract the software to a directory
Configure parameters in config.ini:
- port - the port web.py will host GT-Scan on. A low port number may require superuser privileges. Note also that you may have to try several port numbers to find one that is not already in use.
- ref_genome_dir - the directory containing Bowtie indexed genomes.
- ref_genomes - each line contains the name of a reference genome, in the format: GENOME_NAME = FRIENDLY_NAME
- online_mode - set this to 1.
- mail - SMTP details for outbound mail upon job completion (optional).
- Note - In windows you may need a text editor that can handle Unix newlines, such as Notepad++.
Launch the front-end with: gt-scan_frontend.py.

Front-end server (Apache)

Follow the instructions in this section to use Apache to host the front-end through WSGI. This is not only more flexible than using the built in web.py server, but can also be more stable for a greater number of users. It is, however, much more complicated to set-up.

Extract the software to a directory
Configure Apache to serve gt-scan_frontend.py by adding the following lines to httpd.conf:
- LoadModule wsgi_module modules/mod_wsgi.so
  
  WSGIScriptAlias /gt-scan /var/www/webpy-app/gt-scan_frontend.py/
  AddType text/html .py
  Alias /gt-scan/static /var/www/webpy-app/static/
  <Directory /var/www/webpy-app/>
  Order deny,allow
  Allow from all
  </Directory>
Configure parameters in config.ini:
- ref_genome_dir - the directory containing Bowtie indexed genomes
- ref_genomes - each line contains the name of a reference genome, in the format: GENOME_NAME = FRIENDLY_NAME
- web_root - set this to to the subdirectory Apache is hosting GT-Scan in, i.e. /gt-scan.
- online_mode - set this to 1.
- [mail] (Optional) - SMTP details for outbound mail upon job completion.
  - base_url - set this to your website URL, excluding the directory, for email links to be properly formatted.
Install GT-Scan to the Apache server where TOMCAT_DIRECTORY is the full path to your Apache Tomcat install directory:
- mkdir /var/www/webpy-app
  cp gt-scan_frontend.py /var/www/webpy-app
  cp config.ini /var/www/webpy-app
  cp -r templates/ /var/www/webpy-app
  cp -r static/ /var/www/webpy-app
  cp -r libs/ /var/www/webpy-app
  mkdir /var/www/webpy-app/sessions
  ln -s TOMCAT_DIRECTORY/webapps/ROOT /var/www/webpy-app/static/results
You need to restart your Apache server. An example command for some Linux distributions is: /sbin/service httpd restart
If your Apache installation is at port 80 on your local machine, GT-Scan should now be available at http://localhost/gt-scan/.

Configuring Opal to use PBS (FIXME)

Under construction.

Additional information