SettingUpReactome

From GMOD
Jump to: navigation, search

Reactome Installation Instructions

These installation instructions assume that you have root access to the computer onto which you are planning to install Reactome database and website. The instructions are split into two sections, non-Reactome and Reactome. The first of these involves the installation of applications/modules that are not part of the Reactome project but are necessary for the web site to work, such as Apache and MySQL. The second involves installing the Reactome data, modules and web site code.

You do need to have wget, tar, gcc and (gnu) make. Please make sure that those occur in your path and that the "right" one comes 1st.

Non-Reactome Software

Perl

Reactome Perl scripts expect the Perl to be at /usr/local/bin/perl. If your Perl installation is otherwise up-to-date but the path to it is different, an easy way to rectify the issue is to create a symbolic link at /usr/local/bin/perl pointing to your Perl executable. E.g. if your Perl is located at /usr/bin/perl, do

ln -s /usr/bin/perl* /usr/local/bin

Make sure you have version 5.8.0 or later. If not, install it:

wget http://www.cpan.org/src/stable.tar.gz
  • Unpack it:
tar xvzf stable.tar.gz
  • Enter the created perl-<version> directory.
cd perl-<version>

Configure and compile perl. "-des" makes the Configure script to use default parameters (if you omit it you'll enter an interactive session with the script and have to answer to numerous questions). "-Dprefix=/usr/local" specifies to install perl as "/usr/local/bin/perl". "-Dlibs='-lnsl -ldl -lm -lcrypt -lutil -lc'" instructs to use the specified libraries. W/o "-lm" make would die. "-Duseshrplib" enables shared libraries.

sh Configure -Dprefix=/usr/local -Dlibs='-lnsl -ldl -lm -lcrypt -lutil -lc' -Duseshrplib -des
make
make test
make install
  • You may also want to prepend /usr/local/bin to your path.

Perl modules

The Reactome website needs quite a few Perl modules to be installed in order for it to run. These modules can all be downloaded from www.cpan.org, and are all installed in much the same way: download the compressed archive, unpack in a working directory, and install the module:

tar xvzf module.tar.gz
cd module
/usr/local/bin/perl Makefile.PL
make
make test
make install

Please note that some of these modules require installation of further Perl modules. In addition, some of the modules depend on C libraries or executables that have to be installed before the Perl module in question can be installed successfully. Installation of these also follows similar pattern:

tar xvzf package.tar.gz
cd package
./configure
make
make install

Please note that the last step in both of the instructions above requires you to have the root privileges or execute the command as the root user. The latter is achieved by

sudo make install

Otherwise, you can try to install the modules using

sudo cpan -i MODULE_NAME

for example

sudo cpan -i DBI

List of required Perl modules, their purpose and dependencies is as follows. The dependencies are listed in the order in which they have to be installed.

  • DBI - A common database interface for Perl. Defines a set of methods, variables, and conventions that provide a consistent database interface, independent of the actual database being used. Reactome Perl API uses DBI to interact with Reactome database.
http://search.cpan.org/CPAN/authors/id/T/TI/TIMB/DBI-1.53.tar.gz
  • DBD::mysql - The MySQL drivers for DBI. Mediates communication between DBI and MySQL API.
http://search.cpan.org/CPAN/authors/id/C/CA/CAPTTOFU/DBD-mysql-4.001.tar.gz
  • BioPerl - Perl modules for biology. Please note, though, that only the Bio::Root modules of the BioPerl core package are required. These are used for throwing exceptions and handling file input/output.
http://bioperl.org/DIST/bioperl-1.4.tar.gz
  • GD - Modules for programmatic drawing and manipulation of images. Used for drawing reaction diagrams and "reaction map". The module is an interface to gd graphics library in C (libgd) which is thus also required. libgd is available from www.libgd.org and requires the libpng library for creation and manipulation of images in Portable Network Graphics (PNG) format. libpng further requires zlib compression library.
wget http://www.gzip.org/zlib/zlib-1.2.3.tar.gz
wget http://prdownloads.sourceforge.net/libpng/libpng-1.2.15.tar.gz
wget http://www.boutell.com/gd/http/gd-2.0.33.tar.gz
wget http://search.cpan.org/CPAN/authors/id/L/LD/LDS/GD-2.35.tar.gz
tar xvzf zlib-1.2.3.tar.gz
ln -s zlib-1.2.3.tar.gz zlib
tar xvzf libpng-1.2.15.tar.gz
cd libpng-1.2.15
./configure
make
make install
cd ..
tar xvzf gd-2.0.33.tar.gz
cd ../gd-2.0.33
./configure
cd ..
tar xvzf GD-2.35.tar.gz
cd GD-2.35
perl Makefile.PL
make
make test
make install
For Debian users, you can install this module with
sudo apt-get install libgd-gd2-perl
  • XML::Simple - An Easy API to maintain XML. Used to read an XML configuration file which determines the types of lists downloadable from dynamically created content pages as well as contains the instructions for creating those lists. The module requires XML::Parser Perl module which itself requires expat XML parser library in C. expat is available from sourceforge.net/projects/expat.
http://downloads.sourceforge.net/expat/expat-2.0.0.tar.gz
http://search.cpan.org/CPAN/authors/id/M/MS/MSERGEANT/XML-Parser-2.34.tar.gz
http://search.cpan.org/CPAN/authors/id/G/GR/GRANTM/XML-Simple-2.16.tar.gz
  • PDF::API2 - Module for creation and modification of Portable Document Format (PDF) files. Used for exporting description of Reactome pathways and reactions in PDF. Requires Compress::Zlib, Compress::Raw::Zlib, IO::Compress::Base and IO::Compress::Zlib Perl modules.
http://search.cpan.org/CPAN/authors/id/P/PM/PMQS/Compress-Raw-Zlib-2.003.tar.gz
http://search.cpan.org/CPAN/authors/id/P/PM/PMQS/IO-Compress-Base-2.003.tar.gz
http://search.cpan.org/CPAN/authors/id/P/PM/PMQS/IO-Compress-Zlib-2.003.tar.gz
http://search.cpan.org/CPAN/authors/id/P/PM/PMQS/Compress-Zlib-2.003.tar.gz
http://search.cpan.org/CPAN/authors/id/A/AR/AREIBENS/PDF-API2-0.57.tar.gz
  • GraphViz - Perl interface to the identically named toolkit for layout and image generation of directed and undirected graphs. Used for automatic layout of entity-level pathway diagrams. Please make sure that the directory (/usr/local/bin by default) where graphviz executables (dot, neato, etc) are installed is in your path when installing the GraphViz Perl module.
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-2.12.tar.gz
http://search.cpan.org/CPAN/authors/id/L/LB/LBROCARD/GraphViz-2.02.tar.gz
For Debian users, is possible to install GraphViz with
sudo apt-get install libgraphviz-perl
  • Archive::Tar - Module for manipulations of tar archives. Used for exporting Reactome data as Protege projects. Requires IO::Zlib Perl module.
http://search.cpan.org/CPAN/authors/id/T/TO/TOMHUGHES/IO-Zlib-1.04.tar.gz
http://search.cpan.org/CPAN/authors/id/K/KA/KANE/Archive-Tar-1.30.tar.gz
  • WWW::SearchResult - Class for results returned from WWW::Search
http://cpan.uwinnipeg.ca/cpan/authors/id/M/MT/MTHURN/WWW-Search-2.508.tar.gz
  • Search::Tools::HiLiter - Highlight terms in text
http://cpan.uwinnipeg.ca/cpan/authors/id/K/KA/KARMAN/Search-Tools-0.55.tar.gz
  • Search::Tools::RegExp - Regular expressions
  • Data::CTable - Manipulate tab-separated files
  • 'File::Util - file utilities

MySQL

The easiest way to install MySQL is to use the pre-compiled binaries from http://dev.mysql.com. Although internally Reactome uses version 4.0, versions 4.1 and 5.0 (the stable release at the time of this writing) do also work. Please note, however, that Perl module DBD::mysql (version 4.001, latest at the time of this writing) does not compile against MySQL (mysql-standard-5.0.27-osx10.4-i686 , latest stable release at the time of this writing) on Mac OS X. Please use MySQL 4.1 at least for building DBD::mysql on Macs with Intel processors.

  • Unpack the downloaded file with
tar xvzf MYSQL-VERSION-OS.tar.gz
  • Follow the straightforward installation instructions in the mysql/INSTALL-BINARY file. Please note that your operating system may come with user and group "mysql" created and hence you can skip the 2 first steps.
  • Once the database is running, connect to it as root
/usr/local/mysql/bin/mysql -u root -p mysql

Please note that MySQL will ask you for the root password that you set up during the installation process. Just press the return key if you didn't set up the MySQL root password.

  • Add a MySQL user account that the Reactome web server will be using to connect to the database and retrieve data. In this example the user name is "reactome_user" and the password is "reactome_pass". These will be used later when configuring Reactome web code to access the database.
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP 
ON reactome.* 
TO 'reactome_user'@'localhost' 
IDENTIFIED BY 'reactome_pass';
  • Extend the user's permissions to any database with name containing "reactome":
mysql> UPDATE db SET Db='%reactome%' 
WHERE User='reactome_user';


Apache Web Server

If you don't have Apache web server already, you can download the source code from http://httpd.apache.org/download.cgi. Although Reactome project itself uses version 1.3 of the Apache web server, later versions (2.2.4 is the most recent one at the time of this writing) do also suffice. For installation instructions please follow the appropriate "Documentation" link on the web page.


Apache Tomcat Server

If you don't have Apache Tomcat web server already, you can download the source code from http://tomcat.apache.org/. For installation instructions please follow the appropriate "Download" link on the web page.

Reactome Code and Data

  • Download Reactome website and Perl code, unpack it and move it to /usr/local/reactomes/Reactome/production/GKB:
wget http://www.reactome.org/download/current/GKB.tar.gz
tar xvzf GKB.tar.gz
mv GKB /usr/local/reactomes/Reactome/production/GKB

NOTE: the Reactome downloads page provides the GKB hierarchy for setting up your own Reactome. BUT: this hierarchy is a static version taken at the most recent release, and may therefore be several months out-of-date.

If you require the most up-to-date Reactome code, plus the CVS support, you should check GKB out from CVS instead of downloading it. Proceed as follows:

setenv CVS_RSH ssh (if you use csh or tcsh)

export CVS_RSH=ssh (if you use sh or bash)

cvs -d :ext:formaggio.cshl.org:/usr/local/cvs_repository co GKB

  • Open /usr/local/reactomes/Reactome/production/GKB/modules/GKB/Config.pm with a text editor. Change the value of $JAVA_PATH to reflect the path to the Java (version1.5) executable on your system. Check that the value of $WWW_USER reflects the name of the OS user running the web server. On Mac OS X this is "www" while on unix/linux it tends to be "nobody".

This file also specifies the MySQL user name, password, port and name of the database the web server is using to connect to the database server. Make sure that values of $GK_DB_USER and $GK_DB_PASS are as specified in the MySQL installation step before.

  • Download Reactome data as MySQL database dumps. The 1st of those is the main database while the 2nd one is derived from the main database and supports the skypainter utility of the website.
wget http://www.reactome.org/download/current/sql.gz
wget http://www.reactome.org/download/current/sql_dn.gz
  • Start the MySQL server if it is not running already:
cd /usr/local/mysql
bin/mysqld_safe &
cd -
  • Connect to the database server with MySQL command line client and create empty databases. The name of the main database has to be the same as the value of $GK_DB_NAME in Config.pm. The name of the skypainter database should be the name of the main database with "_dn" appended.
/usr/local/mysql/bin/mysql -u reactome_user -preactome_pass
mysql> CREATE DATABASE reactome;
mysql> CREATE DATABASE reactome_dn;
  • Fill the databases with downloaded data
gunzip -c sql.gz | /usr/local/mysql/bin/mysql -u reactome_user -preactome_pass reactome
gunzip -c sql_dn.gz | /usr/local/mysql/bin/mysql -u reactome_user -preactome_pass reactome_dn
  • A soft link to GKB is needed in /usr/local in order to continue the installation
sudo ln -s path_to_GKB /usr/local/gkb
  • Create the reaction map images and other files that will be used to create the front page of the website. This procedure create a directory with the same names as the main database in /usr/local/reactomes/Reactome/production/GKB/website/html/img-tmp. If you are updating your database rather than doing everything from the scratch, remove this directory first as otherwise the new files will not be created.
/usr/local/reactomes/Reactome/production/GKB/scripts/release/create_frontpage_files.pl
  • Make sure that the the web server can write into and read from the directory used to store the temporary images.
chmod 777 /usr/local/reactomes/Reactome/production/GKB/website/html/img-tmp
The latter makes /usr/local/reactomes/Reactome/production/GKB/website/html/img-tmp directory writable by anybody able to log into the server. If this seems too lax, assign the ownership of this directory to the OS user running the web server and make it writable by this user only. Configure and start Reactome web server
  • Choose the web server configuration file for starting the web server. Reactome distribution comes with one configuration file (httpd.conf.static) for server with compiled-in modules and another one (httpd.conf.dso) for server which uses the Dynamic Shared Object (DSO) mechanism. Both of those files are located in the /usr/local/reactomes/Reactome/production/GKB/website/conf directory. Default Apache server installation compiles all the modules in. However, the server which comes with Mac OS X, for example, uses the DSO mechanism. To determine if your web server has the relevant modules compiled in, invoke the httpd executable with "-l" command line parameter. If the output contains the following in the compiled in module list, use the httpd.conf.static file, otherwise use httpd.conf.dso.
mod_log_config
mod_mime
mod_include
mod_autoindex
mod_dir
mod_cgi
mod_alias
mod_access
mod_so
mod_proxy
mod_proxy_http
For adding the modules, go to /etc/apache2/mods-available folder and execute
a2enmod MODULE_NAME
  • Start the web server with the appropriate configuration file. The following example assumes that the server has compiled-in modules
httpd -f /usr/local/reactomes/Reactome/production/GKB/website/conf/httpd.conf.static

If you are not logged in as the root user, execute the command via sudo. If the httpd executable is not in the root users path, you will have to specify the full path to the httpd executable, i.e. if it is located in /usr/local/apache/bin directory, do

sudo /usr/local/apache/bin/httpd -f /usr/local/reactomes/Reactome/production/GKB/website/conf/httpd.conf.static

If you have a browser on the same computer where you installed Reactome, point your browser at http://127.0.0.1, otherwise replace "127.0.0.1" with the name or IP address of the computer hosting your Reactome web site. You should see the front page of your Reactome installation.

Another option for Debian/Ubuntu users is to add a new site in sites-available. Create a file called reactome in etc/apache2/sites-available and copy the next content:

<VirtualHost localhost:80>
  ServerAdmin joseph.yamada@oicr.on.ca
  ServerName reactomedev.oicr.on.ca
  ServerAlias dev2.reactome.org
  UseCanonicalName on
  Include /usr/local/reactomes/Reactome/development/GKB/website/conf/httpd.conf
  DirectoryIndex index.html index.php

<IfModule mod_deflate.c>
  SetOutputFilter DEFLATE
  AddOutputFilterByType DEFLATE text/*
  DeflateCompressionLevel 9

  BrowserMatch ^Mozilla/4 gzip-only-text/html
  BrowserMatch ^Mozilla/4\.0[678] no-gzip
  BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
 
  SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ \
    no-gzip dont-vary
  SetEnvIfNoCase Request_URI \
    \.(?:exe|t?gz|zip|bz2|sit|rar)$ \
    no-gzip dont-vary
  SetEnvIfNoCase Request_URI \.pdf$ no-gzip dont-vary

# debugging
  DeflateFilterNote Input input_info
  DeflateFilterNote Output output_info
  DeflateFilterNote Ratio ratio_info
  LogFormat '"%r" %{output_info}n/%{input_info}n (%{ratio_info}n%%)' deflate
  CustomLog /var/log/apache2/deflate_log deflate
</IfModule>
</VirtualHost>

Later, execute the next command and restart the apache server

cd /etc/apache2/sites-available
sudo a2ensite reactome
sudo /etc/init.d/apache2 restart

IMPORTANT: You can find the logs in /usr/local/gkb/website/logs folder.

Upgrading Reactome Webapp to the latest version

  • First is necessary to create a new database in MySQL called reactome_pathway_diagram
usr/local/mysql/bin/mysql -u reactome_user -preactome_pass
mysql> CREATE DATABASE reactome_pathway_diagram;
  • Download the data and fill the database
wget http://www.reactome.org/download/current/sql.gz
gunzip -c sql.gz | /usr/local/mysql/bin/mysql -u reactome_user -preactome_pass reactome_pathway_diagram
  • Edit /usr/local/reactomes/Reactome/development/GKB/website/conf/httpd.conf file and scroll down to
ProxyPass  /ReactomeGWT/entrypoint/elv/  http://localhost:8080/ReactomeGWT/entrypoint/elv/
ProxyPass  /ReactomeGWT/entrypoint/  http://localhost:8080/ReactomeGWT/entrypoint/
and check if the tomcat port match with the one configured in your system
NOTE: The latest version of Apache are more restrictives and you can have problems with this proxy configurations. If you receive a 'redirecting error' change this two lines for the next lines (taking into account to change the Tomcat port to the one used in your system)
ProxyRequests On
ProxyPass       /ReactomeGWT/entrypoint/elv/  http://localhost:8080/ReactomeGWT/entrypoint/elv/
ProxyPassReverse /ReactomeGWT/entrypoint/elv/  http://localhost:8080/ReactomeGWT/entrypoint/elv/
<Location /ReactomeGWT/entrypointi/elv>
    DirectoryIndex index.html
    Options Indexes FollowSymlinks MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
    Options +Includes
    XBitHack on
</Location>

ProxyPass       /ReactomeGWT/entrypoint/  http://localhost:8080/ReactomeGWT/entrypoint/
ProxyPassReverse       /ReactomeGWT/entrypoint/  http://localhost:8080/ReactomeGWT/entrypoint/
<Location /ReactomeGWT/entrypoint>
    DirectoryIndex index.html
    Options Indexes FollowSymlinks MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
    Options +Includes
    XBitHack on
</Location>
  • Edit /usr/local/gkb/modules/GKB/Config.pm file and set the next variable as follow:
$USE_REACTOME_GWT = 1;
$DEFAULT_VIEW_FORMAT =  'elv';
$GK_IDB_NAME = 'test_reactome_stable_identifiers';
$SERVLET_CONTAINER_DEPLOY_DIR = "/var/lib/tomcat6/webapps";
this variables are not together in the code. IMPORTANT: $SERVLET_CONTAINER_DEPLOY_DIR is the folder where you have configured your Apache Tomcat server to automatically deploy the war files.
  • Download Reactome stable identifiers data as MySQL database dumps
wget http://www.reactome.org/download/current/test_reactome_stable_identifiers.gz
  • Connect to the database server with MySQL command line client and create a new empty database. The name of the stable identifers database has to be the same as the value of $GK_IDB_NAME in Config.pm.
/usr/local/mysql/bin/mysql -u reactome_user -preactome_pass
mysql> CREATE DATABASE test_reactome_stable_identifiers;
  • Fill the databases with downloaded data
gunzip -c test_reactome_stable_identifiers.gz
| /usr/local/mysql/bin/mysql -u reactome_user -preactome_pass test_reactome_stable_identifiers
  • The next step is copy the gk_current folder containing all the pathway diagrams images to the local system.
    • Connect to reactomedev.oicr.on.ca using your username and password
      ssh username@reactomedev.oicr.on.ca
    • Go to /usr/local/gkbdev/website/html/entitylevelview/pathway_diagram_statics/ folder and compress the gk_current folder
      tar -czvf gk_current.gz gk_current

TO YOUR SYSTEM

    • If doesn't exist, create a folder called pathwaydiagram under /usr/local/gkb/websit/html/entrylevelview/
      mkdir /usr/local/gkb/website/html/entrylevelview/pathwaydiagram
    • Download the gk_current.gz file created in reactomedev.oicr.on.ca
cd /usr/local/gkb/website/html/entitylevelview/pathwaydiagram
scp username@reactomedev.oicr.on.ca:/usr/local/gkbdev/website/html/entitylevelview/pathway_diagram_statics/gk_current.gz .
    • Exctract the content of the gz file
      tar -xzvf gk_current.gz
    • Finally create two soft links in the same folder as follow
ln -s gk_current reactome
ln -s gk_current reactome_pathway_diagram
  • The last step is executing a Perl script for creating the GWT:
perl /usr/local/gkb/scripts/release/create_gwt.pl

'FINALLY: Restart the Apache server and the Apache Tomcat server.

IMPORTANT: If the application does not run, you can check the Tomcat log on your system. In some cases, the username and password for the database access is not correctly copied to the web.xml file inside the WAR file. If this happens, edit the /ReactomeGWT/WEB-INF/web.xml file and write manually the username and password for the database user.

NOTICE: The script create_gwt will write a WAR file in the SERVLET_CONTAINER_DEPLOY_DIR ("/var/lib/tomcat6/webapps"). If not, check the folder permissions. If the WAR file is in this folder, but is not automatically deployed, change the permissions and owner as follow (It's important to know the tomcat user of your system, in the example tomcat will be used)

sudo chmod 755 ReactomeGWT.war
sudo chown tomcat:tomcat ReactomeGWT.war

How to shut down Reactome installation?

  • Stop the web server:
kill `cat /usr/local/reactomes/Reactome/production/GKB/website/logs/httpd.pid`
You have to execute this command as the root user.
  • Stop the MySQL server
/usr/local/mysql/bin/mysqladmin -u root -p shutdown


How to (re-)start Reactome installation?

You have to execute these commands as the root user.

  • Start the MySQL server
/usr/local/mysql/bin/mysqld_safe &
  • Start the web server:
httpd -f /usr/local/reactomes/Reactome/production/GKB/website/conf/httpd.conf.static