=== How to set up a server for BioNetBuilder Cytoscape Plugin === by Iliana Avila-Campillo, May 5th 2006 updated by Kevin Drew, July 17th 2006 updated by Kevin Drew, Sept. 18th 2006 updated by Kevin Drew, Sept. 25th 2006 SUMMARY The backend of BioNetBuilder consists of a mySQL server with several databases and an Apache Tomcat servlet that is deployed through the bionet_server.war . In this document we describe the necessary steps to run the servlet within Apache Tomcat5.5 on a UNIX machine. REQUIREMENTS * Java 5.0 * Apache Tomcat 5.5 * mySQL server (not necessarily running on the same machine as where Tomcat is installed) * The bionet_server.war, the xmlrpc.props properties file (contained within the war file), and the mySQL database scripts can be downloaded from: http://err.bio.nyu.edu/cytoscape/bionetbuilder/downloads.php STEP 1. Installing the server in Tomcat 1.1 Copy the bionet_server.war file into Tomcat's "webapps" directory. For example, my webapps directory is "/usr/local/apache-tomcat-5.5.17/webapps/". 1.2 Tomcat should automatically expand the war file so that you have a new directory inside your webapps directory named bionet_server/. If you don't see the new bionet_server directory immediately you can wait a little longer until Tomcat recognizes the file or restart Tomcat. If after a restart Tomcat still does not recognize the war file, you can expand it manually by running 'jar xvf bionet_server.war' . STEP 2. Setting up the mySQL server Your mySQL server does not necessarily need to be hosted in the same machine as your Tomcat server. You can specify the location of the database in the xmlrpc.props file as you will see if you keep reading. 2.1 For security, create a mySQL account in the server for accessing the databases you are about to create. Consult this page to learn how to create new user accounts: http://dev.mysql.com/doc/refman/5.0/en/adding-users.html For security, our user account has read permissions, but no write permissions. 2.2 Download the mySQL database scripts we have made available at: http://err.bio.nyu.edu/cytoscape/bionetbuilder/downloads/dbScripts.tgz Uncompress them. Then, run the command: perl update.pl -u=db user -p=db password [db=db name] [db2=db2 name] For example: perl update.pl -u=rootuser -p=rootpassword synonyms=synonyms0 prolinks=prolinks0 kegg=kegg0 bind=bind0 go=go0 NOTE: the "rootuser" is for mysql database and not the unix system This step usually takes a long time depending on the speed of your machine and the speed of your internet connection. The script is automated (barring errors) so it is best to let it run overnight. Occasionally you may see perl warnings such as "Use of uninitialized value in split" or "Invalid conversion in printf: "%,". You can safely ignore these warnings. When you are done, your mySQL server should contain these databases: mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | bind0 | | bionetbuilder_info | | go0 | | kegg0 | | prolinks0 | | synonyms0 | +--------------------+ For the following databases, you have to manually download their flat-files (since you will need to register): DIP: Download must be obtained before hand and copied to "dip" directory at the same level as 'update.pl'. The download can be obtained from DIP's website (http://dip.doe-mbi.ucla.edu/, free registration for academic users), and must be in MIF format. Get the "FULL" data set. HPRD: Must download HPRD PSIMI file to "hprd" directory located in the same directory as 'update.pl'. The file (psimi_single_final.xml) can be downloaded for free for academic registered users from HPRD's site: hprd.org BioGRID: The download can be obtained from BioGRIDs website (http://www.thebiogrid.org/, free registration for academic users), and must be in PSI format. Get the "ALL" dataset and place it in a directory called "biogrid" on the same directory as 'update.pl'. When these files are downloaded you can add them like above: perl update.pl -u=rootuser -p=rootpassword synonyms=synonyms0 dip=dip0 hprd=hprd0 biogrid=biogrid0 It is important to update the synonyms database whenever you add or update another database inorder for any new taxids and gene names/ids to be included for querying. Note: Recently(9-20-06), the PIR(http://pir.georgetown.edu/) has choosen to re-support the xml format for the iproclass file. This may not be ready by the time you try downloading the file. If this is the case you will notice an error downloading from the url: ftp://ftp.pir.georgetown.edu/pir_databases/iproclass/iproclass.xml.gz . You can find this url in the update_synonyms_iproclass.pl script and replace it with the older but still relatively current http://err.bio.nyu.edu/cytoscape/bionetbuilder/downloads/iproclass.xml.gz and re-run the script. 2.3 Specify in the xmlrpc.props file, that is contained in your "bionet_server/WEB-INF/classes" directory, the JDBC URL of your mySQL database. To do this, add this entry to it: jdbcURL=jdbc:mysql://hostname.net/bionetbuilder_info?user=username&password=userpassword Instead of "hostname.net" use the address of the machine that is hosting your mySQL server. Instead of "username" and "userpassword" use the name and password of the new user account you created in step 2.1. STEP 3. Restart Tomcat to update recent changes. Almost done. 3.1 Restart tomcat. (For this step, you may need to have the correct permissions.) For example, we do this: sudo /usr/local/apache-tomcat-5.5.17/bin/shutdown.sh sudo /usr/local/apache-tomcat-5.5.17/bin/startup.sh You may have to ask your own systems administrator to restart Tomcat for you. 3.2 Open a web-browser, and test the Tomcat servlet. To do this, type the URL that identifies your Tomcat server plus your own servlet path and name. For example, we type: http://db.systemsbiology.net:8080/bionet_server If everything is in order, you should get a message like this: "HTTP Status 405 - HTTP method GET is not supported by this URL". NOTE: If you receive a timeout error on your browser, you may need to open up the firewall for your server to allow incoming connections to the server on port 8080. If this is not acceptable to your systems administrator for security reasons, you can redirect incoming connections through the Apache2 webserver to your Tomcat server using Apache2's proxy module. For more information on how to use the proxy module see: http://httpd.apache.org/docs/trunk/mod/mod_proxy.html Also, you should see output similar to the log below in Tomcat's catalina.out log (located in the logs directory): -snip- Attempting to start XML-RPC server on port 8085......success! Registering the server as a handler (service "server")......success! Adding service handlers from file xmlrpc.props... SQLSynonymsHandler.makeConnection(null)... Could not make connection to null SQLSynonymsHandler.makeConnection(jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=***)... Try 1: Connecting to mySQL db with url = jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=***... Successfully connected to mySQL database jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=*** SELECT dbname FROM db_name WHERE db="synonyms" Current synonyms database is: [synonyms0] USE synonyms0 Registering a org.isb.bionet.datasource.interactions.InteractionsHandler as a handler (service "interactions")...success! Could not make connection to null Try 1: Connecting to mySQL db with url = jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=***... Successfully connected to mySQL database jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=*** SELECT dbname FROM db_name WHERE db="go" Current GO database is: [go0] USE go0 SELECT id FROM term WHERE term_type = "universal" Registering a org.isb.iavila.ontology.xmlrpc.GOHandler as a handler (service "geneOntology")...success! SQLSynonymsHandler.makeConnection(null)... Could not make connection to null SQLSynonymsHandler.makeConnection(jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=****)... Try 1: Connecting to mySQL db with url = jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=***... Successfully connected to mySQL database jdbc:mysql://pandora.systemsbiology.net/bionetbuilder_info?user=***&password=*** SELECT dbname FROM db_name WHERE db="synonyms" Current synonyms database is: [synonyms0] USE synonyms0 Registering a org.isb.bionet.datasource.synonyms.SQLSynonymsHandler as a handler (service "synonyms")...success! -snip- STEP 4. When running a BioNetBuilder client, how do I redirect it to use my server? Easy. On the plugIns menu in Cytoscape, click on "Set BioNetBuilder Connection..." and type the URL of your servlet. For example, we type: http://db.systemsbiology.net:8080/bionet_server Or, you can add this entry to the xmlrpc.props file for your client: host=http://db.systemsbiology.net:8080/bionet_server DONE!