Personal BLAST Navigator (PLAN) Installation Manual

Table of Contents

0. Preface
1. Getting the Program
2. Installing Required Software
3. Installing PLAN and Setting Directory Permissions
4. Creating Database and Tables
5. Configuring Server Settings and Testing Installation
6. Customizing BLAST Options and User Privileges
7. Common Errors and Resolutions
8. Contacting PLAN Software Authors

0. Preface

Thank you for your interest in installing a local copy of Personal BLAST Navigator (PLAN). This installation manual assumes you are an IT technician and are familiar with routine server administration tasks such as setting directory permissions, installing new Perl modules, and managing rational databases. We provide full technical support of installation, configuration and customization of PLAN to academic users. If you have any questions, please feel free to contact us.

A public PLAN server, open to all academic users, is available at http://bioinfo.noble.org/plan/.

1. Getting the Program

The source code of PLAN is available for free via http://bioinfo.noble.org/plan-download/. You are encouraged to periodically check this web site for the latest version.

2. Installing Required Software

PLAN is platform-independent. It has been well tested on Linux and Windows OS. Before installing PLAN, please make sure your system has the following required software installed:

1. A web server with PHP support. We recommend Apache 2 web server as most decent Linux distributions (e.g. Redhat, Fedora core, SUSE etc.) has it out-of-box. PLAN was developed on PHP 4.0 and has been tested on PHP 5.0. For best compatibility, the most updated version of PHP is recommended.
   
   Windows Users: We recommend the "Web-Developer Server Suite" available at http://www.devside.net/. This server suite provides an all-in-one solution to Apache 2 web server, MySQL 5 database, PHP 5 and Perl 5.8 language and a number of useful tools. Be sure to install the ActivePerl language support available via http://www.activestate.com/Products/ActivePerl/?mp=1 to have Perl language support.
   
   
2. BioPerl. BioPerl, available at http://www.bioperl.org, provides a wide range of Perl modules for handling biological data. Please make sure that you have the latest version (currently v1.5.2) of BioPerl installed.
   
   Unix / Linux Users: Follow the installation manual at http://www.bioperl.org/wiki/Installing_Bioperl_for_Unix to check your BioPerl version and install the latest version.
   
   Windows Users: Follow the installation manual at http://www.bioperl.org/wiki/Installing_Bioperl_on_Windows to check your BioPerl version and install the latest version.
   
   Note: BioPerl v1.3 and v1.4 are found to be buggy and may cause problems in PLAN. If you have to use an old version of BioPerl, make sure you use v1.2.3.
   
   
3. An rational database that is supported by ADOdb and Perl. ADOdb, available at http://adodb.sourceforge.net/, is a database abstraction layer for PHP, which enables PLAN to support multiple database servers transparently. While you certainly may try any database server of your favorite, we highly recommend MySQL server as it is free, cross-platform, built in many Linux distributions, and is what PLAN was originally developed on.
   
   The rest of this installation manual assumes you use MySQL server. If you have to use other database server and are encountering problems installation PLAN, please don't hesitate to contact us.
   
   For the specific database server that you plan to use in PLAN, also make sure that you have installed the corresponding Perl DBD modules. For MySQL server, the module is DBD-mysql. The installation manuals on BioPerl provide a good guide on how to manage Perl modules and install new modules. Please follow the similar process to install the corresponding Perl DBD modules.
   
   Note: You don't have to install ADOdb. The PLAN source code package already has ADOdb integrated.
   
   
4. Decypher client software for integration with Timelogic Decypher server. This is only necessary if you have the access to a Timelogic Decypher hardware BLAST server. Please follow the guidelines provided by Timelogic to install the client software on the machine that PLAN is going to install.
   
   PLAN currently requires Timelogic Decypher server for integrated BLAST searches. You will be able to set up PLAN and use all its post-BLAST functions without a Decypher server. If you want to integrate your software BLAST server into PLAN, please don't hesitate to contact us and we will customize the source code for your particular software environment.

3. Installing PLAN and Setting Directory Permissions

PLAN is distributed in form of plain text PHP and Perl source codes. The package you obtained from the official project site will be in a single ZIP file.

1. Decide the location where PLAN is to be installed. Make sure that the program location is either under your web server's document root, or is mapped to a virtual directory to your web server. For example, if your Apache HTTP server's document root is /var/www and your server's web address is http://yourserver.name, you may install PLAN at /var/www/plan, which makes your PLAN installation accessible via web site http://yourserver.name/plan.
   
   Apache Web Server: The server's document root is specified by the DocumentRoot option in httpd.conf. Use mod_alias to setup a virtual directory if you have to install PLAN out of the range of your document root.
   
   
2. Extract PLAN source code to designated directory. You will need an unzip tool such as WinZip under windows and unzip under Linux to extract all files and sub-directories to the designated directory.
   
   
3. Make data sub-directories writable to web users. The following sub-directories under the extracted PLAN program directory must be writable to web users:
   downloads
   exec
   uploads
   
   Unix / Linux Users: Your web server most likely is running under a user id like apache or nobody. To ensure a directory is writable to web users, do the following:
   chmod a+rwx <directory>
   where <directory> is the subject directory (i.e. download, exec and uploads respectively).
   
   Windows Users: In most cases the mentioned directories are writable to your web users. If you encounter problems with the directory permissions, please double check their NTFS permissions through "Properties" - "Security" from the right-click popup menu on the corresponding directory. Additionally, if you are using IIS web server, read Microsoft KB313075 for more instructions.

4. Creating Database and Tables

It is recommended that you assign a new, empty database to PLAN so that PLAN's database tables won't be mixed with other applications'. You will find a database structure dump file, plan.sql, under /sql sub-directory. Please import this dump file into the new database.

TIP: You may find a number of software tools more helpful to your database management than the conventional command line client program. On MySQL server, we highly recommend phpMyAdmin. The "Web-Developer Server Suite" we mentioned above has phpMyAdmin built-in.

MySQL Users: In case the command line client program is the only one you have access to, do the following to create a new database and import the PLAN dump file:

1. First, login to your server with:
   mysql --host=<host name> --user=<user name> --password=<password>
   where <host name> is your MySQL server's host name (e.g. localhost or myserver.myinstitute.net). <user name> and <password> are the user name (e.g. root) and password required to connect to your MySQL server.
2. Under mysql prompt, create database with:
   create database <database name>;
   where <database name> is the name given to the new database (e.g. plan).
3. Switch to the database that you just created:
   use <database name>;
   where <database name> is the name of the database you created in step 2 (e.g. plan).
4. Finally, import the sql dump file:
   source <full path to the sql dump file>;
   where <full path to the sql dump file> is the location of plan.sql (e.g. /var/www/plan/sql/plan.sql).

5. Configuring Server Settings and Testing Installation

PLAN server settings are saved in a file config_inc.php located in the program root directory. This configuration file has been well-documented with detailed in-line comments. Please follow the comments to configure your server.

Once you have finished editing this configuration file, try visiting PLAN server at your designated address (e.g. http://yourserver.name/plan). You will be able to see the PLAN index page. Test the system by creating a personal account with your email address, log in with your personal account and create a new personal project. You should be able to receive email notifications on the account creation and project creation. If the server does not perform as expected, please refer to Common Errors and Resolutions to check for possible misconfiguration and fixes.

6. Customizing BLAST Options and User Privileges

Some of PLAN's configurations that may require more frequent edition and customization are stored in the file config_customization_inc.php located in the program root directory. This file also has been well-documented with detailed in-line comments. Please follow the comments to customize your "rich display" patterns (e.g. hyper-link highlights on GO and PO terms) and BLAST templates (e.g. Decypher client templates and target databases).

7. Common Errors and Resolutions

This section lists some errors that may occur after your first PLAN installation and the corresponding resolutions. If you are encountering problems that are not covered by this section, please don't hesitate to contact the software authors.

1. Error: 403 (directory listing denied or access forbidden), 404 (page not found) or 500 (internal server error) error when visiting PLAN web site for the first time.

• Resolution: All these errors are caused by web server (NOT PLAN) misconfigurations. For 403 error, please double check that PLAN's program directory is readable to web users and index.php is one of the directory index pages (Apache web server, check DirectoryIndex option). For 404 error, double check if the virtual directory is properly set up if this is the case, also make sure that you visited the correct address (e.g. "/plan/" instead of "/Plan/" in Linux system). Many server misconfigurations may cause a 500 internal server error -- in PLAN's case, most likely PHP installation/configuration. Please refer to your web server installation manual and PHP installation manual to double confirm that PHP is correctly installed on your web server.

2. Error: A plain text error message on database connection (e.g. "Access denied for user 'root'@'localhost' (using password: YES)") when visiting PLAN's home page.

• Resolution: Your database connection configurations are incorrect, PLAN database has not be set up correctly, or your MySQL server is down. Make sure that the PLAN database exists and is accessible, and the database connection configurations in file config_inc.php are correct.

3. Error: Could not receive email notification when a new user or a new private project is created.

• Resolution: Your email configurations in file config_inc.php are incorrect. Nowadays most institutional firewalls block email traffics origined from unauthorized servers, meaning that emails sent with Linux sendmail or PHP internal mail sending function have a very little chance to get through the firewall. The recommended approach is to use your institute's SMTP server (i.e. the server which you use to send and receive your work emails). If you want to install and use PLAN in a long term basis, ask your network administrator to create a special username (mailbox) to send and receive corresponding emails.

4. Error: Could not log in personal account or open a project with correct email/password combination.

• Resolution: This usually indicates either a cookie problem with your web browser, or session logging problem on the server. Double check your web browser has cookie enabled. Clear all your cookies and try logging in / open a project again. If problem persists with PLAN and you don't have cookie problem with other web sites (such as gmail and yahoo! mail which typically require cookie enabled), double check if PLAN server's PHP session directory is writable to web users.
  
  TIP: PHP's session directory is configured with the session.save_path option in php.ini. In windows system, php.ini is normally located under Windows installation directory (e.g. C:\Windows). In Linux/Unix system, php.ini is normally located under /etc.

5. Error: Fail to upload a sequence file or BLAST result file, getting error message "Failed to load uploaded file. Please make sure you have selected the correct file to upload and the file size is within upload size limit."

• Resolution: Usually this indicates a server problem with file upload handling.
  
  First, make sure your file being uploaded is within the size limit set in php.ini. Check the two options, post_max_size and upload_max_filesize, in php.ini to make sure they are being set large enough to handle your files (they are set to only 2M by default). In windows system, php.ini is normally located under Windows installation directory (e.g. C:\Windows). In Linux/Unix system, php.ini is normally located under /etc. Remember to restart your web service after you change the PHP settings.
  
  Also make sure your system temporary directory (e.g. C:\Windows\Temp in Windows and /var/tmp in Linux) is writable to your web server users and there is a large enough disk space left for the temporary directory. If you are using a customized temporary directory for PHP (see upload_tmp_dir option in php.ini), also check it for the same problem.

6. Error: Fail to perform BLAST search, optionally getting an error message "Error submitting search job. Please record possible error message above and contact the system administrator."

• Resolution: Your Decypher client has not been installed/configured correctly to be used by your web server users. If you are getting detailed error message, follow the instruction to resolve the problem. You may also check the detailed error message in your web server's log file (for Apache server, by default it is .\logs\error.log under your Apache program directory (Windows), or /var/log/httpd/error_log (Linux)). This error is commonly caused by either one of the following misconfigurations:
  
  (1). Your DC Client binaries are not found, or access to those binaries are denied: Make sure your configuration $_CFG["BLASTDecypherClientPath"] in config_customization_inc.php under your PLAN installation directory is correct. Make sure your DC Client binaries are executable to your web server users.
  
  TIP: Some Linux distributions have Apache server run as nobody or apache which are dummy user IDs and prevent them from executing local programs. You may solve this by running your Apache server as a registered user ID. Check and edit User and Group settings in your httpd.conf file.
  
  (2). Your template as configured in $_CFG["BLASTDecypherOptions"] (in config_customization_inc.php under your PLAN installation directory) does not exist. Please create the corresponding template file under your DC Client template folder (e.g. /home/dc_client/templates (Linux) or C:\Program Files\timelogic\cli\templates (Windows)).
  
  (3). The target database as configured in $_CFG["BLASTDecypherOptions"] (in config_customization_inc.php under your PLAN installation directory) does not exist. Please create the corresponding target database on your Decypher server.
  

8. Contacting PLAN Software Authors

Currently, PLAN is mainly developed and maintained by Ji He at the Bioinformatics Group of the Samuel Roberts Noble Foundation. Please send your questions, comments, bug reports and new feature requests via http://bioinfo.noble.org/plan/contact.php. You may email Ji He at jhe@noble.org. The project corresponding officer, Patrick Zhao, may be reached through pzhao@noble.org.