Installation Guide v 1.3.0

pedrofeijao edited this page Aug 8, 2011 · 25 revisions

For questions or feedback please write an email to the METAREP mailing list at

Step 1 Install Required 3-rd Party Tools
METAREP uses the following open source tools that need to be installed. Please refer to the individual
tool pages for installation instructions.

CentOS 5.5. installation

  • install minimal CentOS 5.5 version [download]
  • Use CentOS yum package manager to install the following packages
    • mysql.i386 5.0.77-4.el5_5.3
    • R.i386 2.10.0-2.e15
    • perl.i386 4:5.8.8-32.el5_5.1
    • httpd.i386 2.2.3-43.el5.centos.3
    • php.i386 5.2.10-1
  • install Java Runtime Environment and Apache Solr/Lucene (see above).

Step 2 Download and install METAREP source code

  • download METAREP version 1.3.0 [download]
  • untar/unzip
  • move directory to a metarep folder in your Apache Web Server directory,e.g. /<APACHE_WEB_HOME>/htdocs/metarep
  • check that the directory structure under /<APACHE_WEB_HOME>/htdocs/metarep contains an app and a cake directory
  • the path to the metarep directory will subsequently be referred to as <METAREP_HOME>
  • create a symbolic link tmp under the application webroot directory that points to a tmp directory on your system, e.g. /tmp, referred to as METAREP_TMP ln -s METAREP_TMP <METAREP_HOME>/app/webroot/tmp

Step 3 Set up METAREP MySQL database

  • if your have installed MySQL as root and have not yet assigned a password, create a password by executing
    mysqladmin -u root password <password>
  • create the metarep MySQL database by typing mysql -u root -p -e "create database metarep" in the command line or create database metarep using the MySQL client
  • import dump file using mysql -u root -p metarep < /<METAREP_HOME>/mysql/metarep_mysql_dump.sql

Step 4 Set up Gene Ontology MySQL database

  • create a gene_ontology MySQL database by typing mysql -u root -p -e "create database gene_ontology" in the command line or create database gene_ontology using the MySQL client
  • import dump file using mysql -u root -p gene_ontology < /<METAREP_HOME>/mysql/gene_ontology_mysql_dump.sql
    Alternatively, if you wish to import the latest Gene Ontology version, download latest term db dump file from the gene ontology website [download] and import the graph_path and term tables into the gene_ontology database. The other tables are not needed.

Step 5 Set up METAREP Apache Solr/Lucene instance

  • cd into your Apache Solr/Lucene installation directory,e.g apache-solr-3.1.0 (subsequently referred to as <SOLR_HOME> directory)
    cd /<SOLR_HOME>
  • create metarep-solr directory within your Solr home directory
    mkdir /<SOLR_HOME>/metarep-solr
  • copy the METAREP Solr configuration files into the new metarep-solr directory
    cp -a /<METAREP_HOME>/solr/* /<SOLR_HOME>/metarep-solr
  • cd into the example folder of your Solr home directory
    cd /<SOLR_HOME>/example
  • start your Apache Solr/Lucene server. Adjust port (-Djetty.port) and java maximum heap size (-Xmx) if needed.
    java -server -XX:+UseParallelGC -XX:+AggressiveOpts -XX:+DisableExplicitGC -Xms3G -Xmx4G -Djetty.port=1234 -Dsolr.solr.home=/<SOLR_HOME>/metarep-solr -jar start.jar
  • test it at http://localhost:1234/solr . If the page prints ’Welcome to Solr! ’ everything has been correctly set up.

Step 6 Import example datasets

  • download SQLite database that stores KEGG v27 and NCBI taxonomy Feb 2011 attributes from
    ** and gunzip.
  • the import script can be found in the /<METAREP_HOME>/scripts/perl directory
  • the script takes several arguments. Adjust the arguments to match the SQlite, your MySQL and Solr connection parameters. The specified tmp directory will be used to store intermediate XML files. Execute the loading script to import tab delimited example files under /<METAREP_HOME>/data/tab:

perl /<METAREP_HOME>/scripts/perl/ --project_id=1 --project_dir=/<METAREP_HOME>/data/tab --format=tab --sqlitedb=hmp-metarep.sqlite3 --tmp_dir=/<tmp-directory> --mysql_host=<host>:<port> --metarep_db=metarep --metarep_username=<username> --metarep_password=<password> --solr_url=http://localhost:1234 --solr_home_dir=/<SOLR_HOME> --solr_instance_dir=/<SOLR_HOME>/metarep-solr --solr_max_mem 3G

  • check if the tab delimited data load was successful. Go to your Solr default admin page at http://localhost:1234/solr/ (adjust host/port if needed). You should see 7 links that represent the newly loaded datasets. Click on a dataset. Enter ‘protein’ into the Query textfield and hit ‘search’. You should see XML formatted search results. In addition, you can check the number of loaded documents per dataset by using the statistics link at the top menu of the dataset admin page. It displays the number of documents in the stats: section. If you see search results and the document number is higher than zero, your load was successful.
  • Alternatively, to import JCVI Prokaryotic Metagneomics Annotation Pipeline (JPMAP) results specify --format=jpmap. Example JPMAP files can be found under /<METAREP_HOME>/data/jpmap
  • Alternatively, to import HMP Unified Metabolic Analysis Network (HUMAnN) pipeline results specify --format=humann. Example HUMAnN files can be found under /<METAREP_HOME>/data/humann.

Step 7 Adjust METAREP configuration files

  • edit the METAREP configuration file to match your web/solr configuration /<METAREP_HOME>/app/config/metarep.php. Detailed information about each of the variables can be found here
  • edit the database configuration file to connect to your metarep and gene_ontology MySQL databases /<METAREP_HOME>/app/config/database.php.

Step 8 Configure and start Apache web server

  • modify the Apache httpd.conf webserver configuration file to work with mod_rewrite:
    Uncomment the LoadModule rewrite_module .. line so that it looks like this
    # LoadModule foo_module modules/ LoadModule php5_module modules/ LoadModule rewrite_module libexec/apache2/
  • add the following metarep directory configuration
    <Directory /metarep>
    Options FollowSymLinks
    AllowOverride All
  • start Apache web server
    /<APACHE_WEB_HOME>/bin/apachectl start
  • go to http://localhost:80/metarep to see the METAREP welcome page

Step 9 Create new project

  • login as admin
  • click on New Project in the top menu
  • enter project name: ‘HOTS vertical ocean depth profile’
    *enter project description: ‘Planktonic microbial communities in the North Pacific Subtropical Gyre, from the ocean’s surface to near–sea floor’ depths
  • hit the submit button
  • go to http://localhost:80/metarep/projects/view/1 to analyze the project’s datasets

Step 10 Change METAREP admin password

  • login with username:admin and password:admin
  • click on change password on the dashboard page and enter your new admin password