Installation

Installation
Prev	Chapter 1. BII web application 1.4 installation guidelines	Next

Java environment

We recommend having sun JDK 1.6 or higher installed. Please visit Oracle java download pages form more information

Environmental variable JAVA_HOME should also be configured.

For Unix or MacOS users, make sure the following lines are present in .bashrc file:

Prior to install the tools, irrespective of the operating system used, do make sure that Java version 1.6 is deployed on the target machine and that JAVA_HOME environmental variable has been set.

To check which version of Java is currently available, open a terminal and type the following command:

c:>java -version

The result should look like this:

java version "1.6.0_22" Java(TM) SE Runtime Environment (build 1.6.0_22-b04-307-10M3261) Java HotSpot(TM) 64-Bit Server VM (build 17.1-b03-307, mixed mode)

Build environment

BII web application relies on Maven build environment to handle all processes related to dependency handling/downloading. Before starting, make sure Maven tool (version 2.1 and higher) has been installed and properly configured.

Download Maven : Maven 2.2.1

The MAVEN_HOME Environmental variable should also be configured.

Web application server

BII Web application relies on Entreprise Tools such as Jboss Seam web application server.

Download Jboss : Jboss seam version 4.2.3GA up to 5.1.0.GA

BII Web application 1.4 has been tested successfully on the following Jboss version:

Do check that JBoss web application server has been correctly installed. If testing on your local machine, open a web browser and point it to the following URL, http://localhost:8080 It should show the following:

If you don't, you may have an application (possibly apache) already listening to port 8080.

Changing Default Port

A lot is available from the Jboss community, we recommend starting here.

Starting from Jboss 5, the process essentially relies on starting jboss server by passing the virtual machine the jboss.service.binding.set argument as in:

run -Djboss.service.binding.set=ports-01

Alternately, editing the "server/default/conf/bindingservice.beans/META-INF/bindings-jboss-beans.xml" file. Refer to the link indicated above for more details.

Configuring Jboss to run multiple instances of BII

work in progress. this section will be updated soon

Enabling authentication with LDAP server

work in progress. this section will be updated soon but some documentation is already available here

Relational Database Management System

BII Web application ships with profiles for H2, Oracle, MySQL and Postgresql RDBMS

H2 database

H2 database version 1.0.76
JDBC driver version 1.0.76
H2 does not need any configuration and was used as test environment

PostgreSQL database

PostgreSQL 8.4.1
JDBC driver version postgresql-8.4-701.jdbc3.jar
create a database namespace, in our example called 'bioinvindex'
To do so, connect to PostgreSQL database server issueing the following command from a terminal:
$/Library/PostgreSQL/8.4/bin/createdb -U postgresuser -E UTF-8 -e bioinvindex
Supply the password associated to user "postgresuser". Now, ensure that the database has been successfully created by issueing:
$/Library/PostgreSQL/8.4/bin/psql -U postgresuser bioinvindex
Alternately, one could rely on administration tools such pgAdminIII to perform the set up.

MySQL database

MySQL database version 5.39
JDBC driver version 5.1.10
create a database namespace, in our example called 'bioinvindex'
To do so, connect to MySQL database server issueing the following command from a terminal:
>mysql -u mysqluser -p
Supply the password associated to user "mysqluser" and from the mysql prompt, issue
mysql>CREATE DATABASE bioinvindex DEFAULT CHARACTER SET utf8;
This command should display the following information (or similar)
Password for user postgres:
psql (8.4.1)
Type "help" for help.
bioinvindex#
Alternately, one could rely on administration tools such phpMyAdmin

Oracle database

Oracle database 11g
JDBC driver version 11.1.0.7.0
Consult with your Oracle DBA in order to configure a database.

	Note
	Due to legal issue, we can not redistribute Oracle products. Oracle JDBC driver is available from here:

ISA softwares: BII Data Manager and BII Web application

Warning

As we stated earlier, for BII Data Manager and BII Web application to work together, both tools need to be configured so that the following parameters are the same:

Database connection parameters
Lucene Index location
Datafile locations

We will now details how to set those parameters for each of the tools.

Editing hibernate.properties file to configure BII-Data-Manager

After having downloaded and uncompressed the BII-Data-Manager archive, navigate the ./BII-data-manager-1.3/config folder. The folder contains 4 hibernate.properties files, one for each the database profiles.

Pick the one you need and edit as follows:

database configuration parameters

The example below is for a mysql environment

              
                                 ====================  
                                 mysql database configuration
                                 ====================
                                 hibernate.connection.username=CHANGEME
                                 hibernate.connection.password=CHANGEME
                                 hibernate.connection.url=jdbc:mysql:/CHANGEME
                                 hibernate.connection.driver_class=com.mysql.jdbc.Driver
                                 hibernate.dialog=org.hibernate.dialect.MySQL5InnoDBDialect

database indexing and search parameters

                                
                                hibernate.search.default.directory_provider=prg.hibernate.search.store.FSDirectoryProvider
                                hibernate.search.default.indexBase=/vol/bioinvindex/lucene/
                                hibernate.search.indexing_strategy=manual

	Note
	The path supplied to the indexBase should be the absolute path.

Make JDBC driver available to BII-Data-Manager

navigate the ./BII-data-manager-1.3/ folder and locate the run.bat file you are a Windows user or the run.sh file if running Mac OSX or Linux. Edit the file as follows:

JDBCPATH=/Users/johnsmith/jdbc_drivers/mysql-connector-java.jar

If using windows, it will look like this

SET JDBCPATH=C:\Users\johnsmith\jdbc_drivers\mysql-connector-java.jar

Edit the 'data_location.xml' file

Why do I need to do this?

Well, when persisting ISA-Tab formatted experimental data, BII-Data-Manager handles datafiles (image files, raw data file, derived data files) to a specific location o n the file system so they can be served by the web application for users to download. So BII-data-manager needs to know how to form valid URLs allowing access from the pages served by the web application. The following steps detail how to perform this configuration task.

navigate the ./BII-data-manager-1.3/config folder and locate the 'data_locations.xml' file.Edit the file as follows:

Set filesystem_path parameter
JDBCPATH=/Users/johnsmith/jdbc_drivers/mysql-connector-java.jar
Set web_url parameter
web_rul=file:///tmp/bii_test_repo/microarray/study_${study-acc}/raw_data

If using windows, it will look like this

Warning

Set Permissions Appropriately

This is an important point. the BII-Data Manager needs to be granted read and write access rights to the chosen location for dispatching datafiles,logs and lucene indices during loading.

Configuring and Building BII-Web application

Editing `profiles.xml` file to configure BII-Web application 1.4

After having downloaded and uncompressed the BII-Web Application archive, navigate the ./BioInvIndex-1.4/. The folder content should look like this:

Open the profiles.xml file in a text editor and navigate the relevent database profile (choose from h2, mysql, postgres or oracle).

database configuration parameters

The example below is for a mysql environment

                             
                                <profile>
                                    <id>mysql</id>
                                    <activation>
                                        <activeByDefault>false</activeByDefault>
                                    </activation>
                                    <properties>
                                        <hibernate.dialect>org.hibernate.dialect.MySQL5InnoDBDialect</hibernate.dialect>
                                        <jdbc.groupId>mysql</jdbc.groupId>
                                        <jdbc.artifactId>mysql-connector-java</jdbc.artifactId>
                                        <jdbc.version>5.1.6</jdbc.version>
                                        <jdbc.driverClassName>com.mysql.jdbc.Driver</jdbc.driverClassName>
                                        <jdbc.url>jdbc:mysql://localhost:33066/bioinvindex?profileSQL=false</jdbc.url>
                                        <jdbc.username>USERNAME</jdbc.username>
                                        <jdbc.password>PASSWD</jdbc.password>
                                    </properties>
                              </profile>

set location to the lucene index file, required for database indexing and searches

                               
                               <profile>
                                    <id>index_local</id>
                                    <activation>
                                        <activeByDefault>false</activeByDefault>
                                    </activation>
                                    <properties>
                                        <hibernate.search.default.indexBase>/vol/bioinvindex/lucene/</hibernate.search.default.indexBase>
                                    </properties>
                                </profile>

	Note
	The path supplied to the indexBase should be the absolute path.

	Warning
	Ensure that this path matches the one used when configuring the BII-Data-Manager while editing the hibernate.properties files. Failing to do will results in failure to properly list studies from the web application, and prevent from carrying out normal searches. Do double check!

Building BII-web application with Maven

	Note
	This step requires Maven to be installed and properly configured. See section 1 for more information.

Once the 'profiles.xml' has been edited as instructed and save, it is possible to build the BII web application by issuing the following command:

Using an H2 database
>mvn clean package -Ph2,index_local -Dmaven.test.skip=true
Using an Oracle database
>mvn clean package -Poracle,index_local -Dmaven.test.skip=true
Using an mySQL database
>mvn clean package -Pmysql,index_local -Dmaven.test.skip=true
Using an PostgreSQL database
>mvn clean package -Ppostgresql,index_local -Dmaven.test.skip=true

If all goes well, the process will create a 'target' directory as follows: ./BioInvIndex-1.3/ear/target containing the bii-1.3.ear file.

Deploying BII-web application on Jboss Seam web application server

To deploy the BII webapplication, simply copy the bii-1.3.ear file from the ./BioInvIndex-1.3/ear/target to the '../jboss/server/default/deploy' location.

>cd /ear/target

>mv bii-1.3.ear [path to JBOSS]/jboss/server/default/deploy

Starting the web application server

Start Jboss web application server running the following command.

>cd /path/to/jboss_installation/jboss/bin/

>./run.sh (Mac OS/Linux) or >./run.bat (windows)

Checking the BII-web application is up and running

Simply start a web browser and point to the following URL http://localhost:8080/bioinvindex, assuming the database namespace is bioinvindex and that port 8080 is available to Jboss. Please refer to the troubleshooting section if necessary.