miRvestigator web server
========================

  Copyright (C) 2010 by Institute for Systems Biology,
  Seattle, Washington, USA.  All rights reserved.

  This source code is distributed under the GNU Lesser
  General Public License, the text of which is available at:
    http://www.gnu.org/copyleft/lesser.html


We developed this to provide a natively python web server implementation of the miRvestigator framework (please see http://github.com/cplaisier/miRvestigator). The implementation is broken up into a daemon which forks multiple worker processes that run the miRvestigator algorithm and a client running in mod_python in an Apache2 web server. A running example can be found at:  http://mirvestigator.systemsbiology.net

miRvestigator web server has the following dependencies:
 * Python 2.4 or 2.6 (www.python.org)
 * Pyro 3.9.1 (http://www.xs4all.nl/~irmen/pyro3/)
 * Apache2 HTTP server (httpd.apache.org)
 * mod_python 3.3.1 (www.modpython.org)
 * Weeder1.4.2 (http://159.149.109.9/modtools/)
 * WebLogo (for motif logo plots)
 * MySQL
 * python-mysql
 * postfix (or other SMTP server)
 * ViennaRNA (for RNA free energy calculation)

Web server files located in the miRvestigator/client sub-tree need to be copied to a directory served by the Apache web server (/var/www/ in our AMI) with the following settings:

<Directory /web/served/directory>
  AddHandler mod_python .py
  PythonHandler mod_python.publisher
  PythonDebug On
  Options -Indexes FollowSymLinks MultiViews
  AllowOverride None
  Order allow,deny
  allow from all

  RewriteEngine ON
  RewriteRule ^status/([a-fA-F0-9\-]+)/(.?)$ /status/index.html [L]
  RewriteRule ^results/([a-fA-F0-9\-]+)/(.?)$ /miRvestigator.py/results?id=$1 [L]
  RewriteRule ^sites/csv/([0-9]+)(.?)$ /miRvestigator.py/sites_as_csv?motif_id=$1 [L]
  RewriteRule ^scores/csv/([0-9]+)(.?)$ /miRvestigator.py/scores_as_csv?motif_id=$1 [L]
  RewriteRule ^error/([a-fA-F0-9\-]+)/(.?)$ /error/index.html [L]
  RewriteRule ^error$ /error/index.html [L]
</Directory>

Adding MultiviewsMatch Handlers is required for urls like /miRvestigator/status?id=XXX to match miRvestigator.py.

MySQL and python-mysql need to be installed. A database called mirvestigator needs to be created and populated with tables like this:
mysql -p -u root --database mirvestigator < mirvestigator.sql

The user 'mirvestigator'@'localhost' needs to exist and login credentials supplied in mirv_db.py. Also, see comments in mirvestigator.sql. Default username and password should be changed after installation. Mysql's root uses the name of the db as a password. This can be changed like this:
mysqladmin -u root password NEWPASSWORD

The miRvestigator/server scripts can be installed anywhere but the server must be able to access the Weeder programs. We typically put these into a bin that is part of the PATH and modify the C code to point specifically at the other programs needed and the FreqFiles. FreqFiles are used to compute background model and are located (on our AMI) in /home/ubuntu/bin/FreqFiles.

The server files are:
 * mirv_server.py - Creates a Pyro daemon which enqueues requests from the web tier.
 * mirv_worker.py - server starts up a worker for each core.
 * mirv_db.py - Interfaces with MySQL for storing requests and retrieving results.
 * admin_emailer.py - Sends email on successful completion of jobs or on errors.
 * miRvestigator.py - Different than the client miRvestigator.py, as this is the actual class that does the work for miRvestigator.
 * pssm.py - A class designed to be a container for a Position Specific Scoring Matrix (PSSM).
 * p3utrSeqs_[species_name].csv - A csv file for each species containing all the 3' UTR sequences for genes with genomic coordinates annotated with Entrez gene IDs.

For custom installations, the mirv_worker.py script will need to be modified to make sure that weederlauncher program location is correct. In mirv_server.py, we write the URI of the Pyro server in a known location so that the web tier can find it (to avoid the hassle of using a name server). Make sure that the location of the Pyro URI saved file is writable by the server. Then we start up a screen instance and inside that start the daemon by:

python mirv_server.py

The daemon should save its URI in the designated file and then be ready for a client to access it and run the miRvestigator framework. Test it by navigating to the machine with your browser and clicking one of the sample data buttons. If that works, you are ready to try it with some of your own data.

There is a csv file for each species containing 3' UTR sequences, which needs to be placed in the miRwww_server directory.
 * p3utrSeqs_Caenorhabditis_elegans.csv
 * p3utrSeqs_Drosophila_melanogaster.csv
 * p3utrSeqs_Gallus_gallus.csv
 * p3utrSeqs_Homo_sapiens.csv
 * p3utrSeqs_Mus_musculus.csv
 * p3utrSeqs_Rattus_norvegicus.csv

We have been able to get this up and running on EC2 using Ubuntu 10.04 LTS Lucid instance-store image (ami-da0cf8b3) from alestic.com and will provide our own mirvestigator image with all dependencies installed. Using an EC2 High-CPU Medium Instance (1.7GB of memory, 5 EC2 compute units (2 virtual cores with 2.5 EC2 Compute Units Each, 350GB of local instance storage, 32bit OS) it took 2 minutes to analyze 13 genes in miRvestigator, and with 106 genes it took 7.4 minutes.