BioUML installation

This page describes how to install BioUML server provided that you have a CVS access to BioUML sources.

Paths

The following paths will be referred within this document:

• $SERVER_PATH - path to main BioUML installation folder. Usually it’s /opt/BioUML_Server.
• $CATALINA_HOME - path to tomcat folder.
• $SOURCES - path to BioUML sources

Prerequisites

• Linux server. Ubuntu preferred.
• Java. Oracle JDK 1.6 preferred, but OpenJDK 1.6 and Oracle Java 1.7 also work.
• Apache Tomcat (6+).

aptitude install tomcat6

• Apache Ant.

aptitude install ant

If you see compilation error about org.apache.tools.ant.util.regexp.Jdk14RegexpRegexp, you have to install one of the following:

aptitude install ant-optional
aptitude install ant-apache-regexp

• MySQL (5+):

aptitude install mysql-server-5.1

• R (required for some functions such as microarray data normalization) — see below.
• Galaxy (required if you want to use Galaxy analyses or create your own analyses using Galaxy interface)
• Eclipse Java IDE (preferred IDE for development, you may use others as well).

R installation

• R itself:

yum install R

or

apt-get install r-recommended

• Rserve:

apt-get install r-cran-rserve

• BioConductor (from R-console):

source("http://bioconductor.org/biocLite.R")
biocLite()
biocLite("makecdfenv", lib="/usr/local/lib/R/site-library")

• Illumina normalization (from R-console):

biocLite("lumi")

Note that this step may require installation of additional packages in the system like libxml2-dev, libglut3-dev, libcurl4-gnutls-dev.

• Agilent normalization (from R-console):

biocLite("limma")

BioStore server registration

In order to activate user account management server should be registered in BioStore system. For this perform the following steps:

• Register in the BioStore: https://bio-store.org/biostore/ (leave “My first project” fields empty)
• Write an e-mail to us specifying the following information:
  • The stable Internet address of your server (host:port). If it’s accessible via local network only, then it’s ok to specify your local address.
  • User-friendly server name.
  • List of logins (e-mails) registered via BioStore who should become server administrators.
• We will create the server entry and change the permission settings, so you will be able to administer the server.

Further there will be special form for automated server registration via Biostore

Getting sources

CVS: use the following CVS-root:

:pserver:<username>@cvs.developmentontheedge.com:/usr/cvsroot-biouml (please request an account via e-mail)

Security properties

• Enable everything in /usr/lib/jvm/java-6-sun/jre/lib/security/java.policy (or the corresponding file in your Java installation):

grant {
  permission java.security.AllPermission;
};

• Enable everything in tomcat policy: $CATALINA_HOME/conf/catalina.policy (or policy.d): in the same way.

Deployment prepare

Specify $SERVER_PATH in BioUML/src/build.xml:

<property name="SERVER_PATH" value="C:/BioUML_Server_0.9.4" />

Change it to the appropriate value.

Depending on your Tomcat installation you may need to define DEPLOY_DIR inside “deploy.server” target. Add

<property name="DEPLOY_DIR" value="$CATALINA_HOME/webapps/biouml" />

Subdirectories in $SERVER_PATH

The following should be located in $SERVER_PATH:

• preferences.xml: copy $SOURCE/BioUML/preferences_server.xml, edit or remove “Proxy” section and “ServerLink” in “Global”.
• analyses: copy $SOURCE/BioUML/analyses, edit “Galaxy/default.config” if necessary.
• configuration, history, users: will be created automatically during build.
• plugins: create a symlink from $SOURCE/BioUML/plugins to $SERVER_PATH/plugins:

ln -s $SOURCE//BioUML/plugins $SERVER_PATH/plugins

• repo: create the folder and copy contents of BioUML/data_network. New databases will be installed here (it will be discussed later). In security.properties file you should specify your stable server address (the same as registered via BioStore) in “securityProviderServer” field.
• resources: create the folder and copy contents of BioUML/data_resources_network.

All files in $SERVER_PATH (except plugins directory) must be owned by tomcat user (usually ‘tomcat6’). Use:

chown -R tomcat6.tomcat6 $SERVER_PATH/*

Ensure that tomcat user (usually ‘tomcat6’) has enough access rights to read $SERVER_PATH/plugins directory.

bioumlsupport2 database

• Create database bioumlsupport2. In MySQL console:

create database bioumlsupport2;
grant all on bioumlsupport2.* to ‘bioumlsupport2’@’localhost’ identified by ‘bioumlsupport2’;

• Import $SOURCE/BioUML/dumps/bioumlsupport2.dump.sql into the newly-created database.
• Add administrative MySQL rights to bioumlsupport2 user (it’s used to create new projects)

grant all privileges on *.* to `bioumlsupport2`@'localhost' with grant option;
grant all privileges on *.* to `bioumlsupport2`@'%' with grant option;

Web files

Static web files should be available in $CATALINA_HOME/webapps/bioumlweb. Create a symlink from $SOURCE/BioUML/src/ru/biosoft/server/servlets/webservices/webfiles:

ln -s $SOURCE/BioUML/src/ru/biosoft/server/servlets/webservices/webfiles $CATALINA_HOME/webapps/bioumlweb

Ensure that tomcat user (usually ‘tomcat6’) has enough access rights to read bioumlweb directory.

Look into $CATALINA_HOME/webapps/bioumlweb/defines.js file. You may need to change “serverAddress” and probably other fields. Do not change “serverPath” field (it’s URI to BioUML server).

intro.html is the start page. You may edit it as you want.

SimulationEngine workaround

Comment following lines in build_bdk.xml:

After compilation copy the following files from $SOURCE/BioUML/out to $CATALINA_HOME/out (usually /var/lib/tomcat6/out):

• biouml/plugins/simulation/Model.class
• biouml/plugins/simulation/ae/AeModel.class
• biouml/plugins/simulation/ae/NewtonSolver.class
• biouml/plugins/simulation/java/JavaBaseModel.class
• biouml/plugins/simulation/ode/OdeModel.class
• ru/biosoft/math/MathRoutines.class.

Logging

Logging configuration is in $SOURCE/BioUML/server.lcf file. Put it into $CATALINA_HOME, edit if necessary.

Compilation

Compile in $SOURCE/BioUML/src. In general you should not edit build_bdk.xml: use clean CVS versionrc directory. Some settings should be fixed in build.xml file (see above). To rebuild everything use: ant deploy.server. Make sure that after build biouml.war appears in $CATALINA_HOME/webapps. If not, probably there’s some misconfiguration in build.xml.

To rebuild most of plugins only (faster): ant plugin.all

Rebuild specific plugin: ant plugin.<name> or ant server.servlets. See build.xml/build_bdk.xml for details.

Clean: ant clean.

Launch

(Re)start tomcat server to get new changes.

Open in the browser: http://localhost:8080/bioumlweb/ (address may differ if you changed the tomcat settings)

Troubleshooting

Eclipse platform caches plugins configuration inside $SERVER_PATH/configuration/org.eclipse.* directories. If you feel that plugins configuration might change or experience strange errors after server restart, try to stop server, remove these directories and start it again. Actually you may remove them every time you restart the server (for example, by adding an appropriate command into server restart script).

Logs

• Tomcat launch problems in $CATALINA_HOME/logs/catalina.out
• BioUML launch problems in $SERVER_PATH/configuration/*.log (the most recent one)
• BioUML running problems in $CATALINA_HOME/logs/biouml_server.log (though many junk messages are also appear there)