BioCoRE - Biological Collaborative Research Environment

Install BioCoRE files

In the MySQL installation step you unpacked a biocore.war file.

Change to the $BIOCORE_HOME/packages/tomcat/current/webapps directory and create a subdirectory called biocore. Change to the new directory you just created, and unpack the biocore.war file: 

$BIOCORE_HOME/java/current/bin/jar xf /PATH/TO/biocore.war

This will uncompress the WAR file.

BioCoRE Context Configuration File

In the $BIOCORE_HOME/packages/tomcat/conf/Catalina/localhost directory, you need to create a file called biocore.xml. Download the file here, or use your favorite text editor and copy in the following: 

<!-- Tomcat BioCoRE Context Configuration File -->
<Context path="/biocore" docBase="biocore"  >


   <!-- Logging and debugging mail setup -->
   <Environment name="FileLogFile" type="java.lang.String"
                value="/tmp/biocore.log" />
   <Environment name="ErrorMailSMTPHost" type="java.lang.String"
                value="localhost" />
   <Environment name="ErrorMailFromAddress" type="java.lang.String"
                value="DevBioCoREServer@your.site.edu" />
   <!-- multiple addresses can be me@uiuc.edu,you@uiuc.edu -->
   <Environment name="ErrorMailToAddress" type="java.lang.String"
                value="youremail@your.site.edu" />

   <Logger className="org.apache.catalina.logger.FileLogger"
         prefix="localhost_biocore_log." suffix=".txt" timestamp="true"/>

   <!-- Mail setup that BioCoRE will use to send mail to users -->
   <Resource name="mail/biocoreJavaMail" auth="Container"
         type="javax.mail.Session"/>

   <ResourceParams name="mail/biocoreJavaMail">
      <parameter>
           <name>mail.smtp.host</name>
           <value>localhost</value>
      </parameter>
   </ResourceParams>

<!--
If you are wanting to use SMTP-AUTH, you need to move the following
parameter settings up above into the ResourceParams for 
javamail/biocoreJavaMail.
In addation, you might need to add mail.smtp.saslrealm.  See 
http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html

      <parameter>
           <name>mail.smtp.user</name>
           <value>username</value>
      </parameter>
      <parameter>
           <name>mail.smtp.auth</name>
           <value>true</value>
      </parameter>
-->


   <!-- Database setup -->
   <Resource name="jdbc/biocoreJDBC" auth="Container"
         type="javax.sql.DataSource"/>

   <ResourceParams name="jdbc/biocoreJDBC">
<!--
MySQL dB username and password for dB connections 
-->
      <parameter>
         <name>username</name>
         <value>DBUSER</value>
      </parameter>
      <parameter>
         <name>password</name>
         <value>DBPASS</value>
      </parameter>
        
<!--
The JDBC connection url for connecting to your MySQL dB.
The autoReconnect=true argument to the url makes sure that the
mm.mysql JDBC Driver will automatically reconnect if mysqld closed the
connection.  mysqld by default closes idle connections after 8 hours.
The zeroDateTimeBehavior allows the newer versions of the driver to work
and doesn't affect older versions.
-->

      <parameter>
         <name>url</name>
<value>jdbc:mysql://VALUEOFLOCALURL?autoReconnect=true&amp;zeroDateTimeBehavior=convertToNull</value>
      </parameter>

      <parameter>
         <name>factory</name>
         <value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
      </parameter>

<!--
Maximum number of dB connections in pool. Make sure you
configure your mysqld max_connections large enough to handle
all of your db connections. Set to 0 for no limit.
-->

      <parameter>
         <name>maxActive</name>
         <value>6</value>
      </parameter>
        
<!--
Maximum number of idle dB connections to retain in pool.
Set to 0 for no limit.
-->

      <parameter>
         <name>maxIdle</name>
         <value>3</value>
      </parameter>
        
<!--
Maximum time to wait for a dB connection to become available
in ms, in this example 10 seconds. An Exception is thrown if
this timeout is exceeded.  Set to -1 to wait indefinitely.
-->

      <parameter>
         <name>maxWait</name>
         <value>10000</value>
      </parameter>

<!--
get rid of abandoned connections if they don't get dropped 
defaults to doing this after 300 seconds                  
-->
      <parameter>
         <name>removeAbandoned</name>
         <value>true</value>
      </parameter>

<!--
set timeout to 60 seconds instead of the default 300
-->
      <parameter>
         <name>removeAbandonedTimeout</name>
         <value>60</value>
      </parameter>



<!--
log the fact that we had to kill a connection
-->
      <parameter>
         <name>logAbandoned</name>
         <value>true</value>
      </parameter>
 
<!--
Class name for mm.mysql JDBC driver
         <value>org.gjt.mm.mysql.Driver</value>
Class name for the connector         (although mm.mysql still works)
         <value>com.mysql.jdbc.Driver</value>
-->
      <parameter>
         <name>driverClassName</name>
         <value>org.gjt.mm.mysql.Driver</value>
      </parameter>

   </ResourceParams>
        

</Context>
Notes:
  • This tells Tomcat that you want to access the BioCoRE server at http://your.machine/biocore/. If you want it to be at a location other than /biocore, you can change the 'path' given on the Context line at the top of the file.
  • The FileLogFile environment variable is currently set to /tmp/biocore.log. You likely want to change it to a different location. This log file contains logging ouput that the programmers have written into the BioCoRE server. It is a good idea to check this file occasionally for aberrations.
  • The ErrorMailSMTPHost environment variable is currently set to localhost. If the mailserver you use isn't running on localhost, you should change this value to whatever machine is configured in your organization to send mail. Error mail is sent when Tomcat observes an error with your server. Normal mail that the BioCoRE server sends to users is handled farther down in the file.
  • The ErrorMailFromAddress environment variable is currently set to DevBioCoREServer@your.site.edu. Error mail will have this address as the From: address. Depending on the settings on your mail server, this might need to correspond to an actual user on your system.
  • The ErrorMailToAddress environment variable is currently set to youremail@your.site.edu. You need to change this to your own email address. When Tomcat detects a problem, this is who will get email about it. You can specify multiple email addresses. Just separate them with a comma.
  • The FileLogger can probably be left as is. Some Tomcat messages for BioCoRE will go into a file named with a prefix of localhost_biocore_log in the $TOMCAT_HOME/logs directory.
  • The mail/biocoreJavaMail section configures mail that the BioCoRE server sends to users, such as welcome email, project invitation email, etc. The <value> parameter for the mail.smtp.host needs to be changed to your SMTP machine name. This will almost certainly need to be the same as what you set for the ErrorMailSMTPHost above. The only reason it would be different is if you have two different mail servers that you use (one for internal mail; one for external mail) for some reason. In that case, you would probably want to set the Error server to your internal mail server, but set the biocoreJavaMail values to the mail server that can send mail to the world.
  • In the jdbc/biocoreJDBC resource area, there are three values that you will need to change.
    • DBUSER - This value is required. The section that looks like: 
      <parameter>
   <name>username</name>
   <value>DBUSER</value>
</parameter>
      needs to be revised to look something like the following (being sure to replace 'bcdbuser' with whatever MySQL username you set when you installed MySQL). 
      <parameter>
   <name>username</name>
   <value>bcdbuser</value>
</parameter>
    • DBPASS - This value should be replaced with the password specified when you set up the user for MySQL.
    • VALUEOFLOCALURL - This value is required. This will be something like: 
      your.machine.edu:3306/biocore
      You need to make sure that: the machine name where your database is at (your.machine.edu in this case) is correct, the port number that you are running the database on (3306 in this case) is correct, and the name of the database (biocore in this case) is correct. (NOTE: IF you don't know your port number, use 3306. This is the default MySQL port and is probably what you want) This will result in that section looking something like: 
      <name>url</name>
<value>jdbc:mysql://your.machine.edu:3306/biocore?autoReconnect=true&amp;zeroDateTimeBehavior=convertToNull</value>
</parameter>

    Next Step: Set up a BioCoRE configuration file.
    Back to the installation page

    Feedback

    The BioCoRE team welcomes any comments, questions, or suggestions that you might have concerning our software! Please email us or fill out our feedback form.