View source for BioUML server 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.8 or OpenJDK 1.8.
* Apache Tomcat (7+).
 aptitude install tomcat7
* 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
* R (required for some functions such as microarray data normalization) — see [[R installation]] page.
* 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).

== 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

== Development installation ==
For internal development installation you may skip the BioStore integration. Instead write the following in the security.properties file:

 jdbcDriverClass=org.gjt.mm.mysql.Driver
 jdbcURL=jdbc:mysql://lachesis:3306/bioumlsupport2
 jdbcUser=bioumlsupport2
 jdbcPassword=bioumlsupport2

 securityProvider=ru.biosoft.access.security.TestSecurityProvider
 products=Server;Import;R;Experimental

This will bypass the authentication and authorization: every user with any password will have administrative privileges and subscription to the specified products. Change the list of the products if necessary.

== Getting sources ==
CVS: use the following CVS-root:
 :pserver:<username>@cvs.developmentontheedge.com:/usr/cvsroot-biouml (please request an account via e-mail)

== 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 some fields there.

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

=== SimulationEngine workaround ===
Comment following lines in build_bdk.xml:
 <nowiki>
<!-- copy file="${TOPDIR}/server.lcf" tofile="${TOMCAT_PROJECT_PATH}/../../server.lcf" />
<copy todir="${TOMCAT_PROJECT_PATH}/../../bin/out">
<fileset dir="${OUTDIR}">
 <include name="biouml/plugins/simulation/Model.class" />
 <include name="biouml/plugins/simulation/ae/AeModel.class" />
 <include name="biouml/plugins/simulation/ae/NewtonSolver.class" />
 <include name="biouml/plugins/simulation/java/JavaBaseModel.class" />
 <include name="biouml/plugins/simulation/ode/OdeModel.class" />
 <include name="ru/biosoft/math/MathRoutines.class" />
</fileset>
</copy--></nowiki>

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.

=== Security properties ===
* Add the following line into policy file ( /usr/lib/jvm/java-8-oracle/jre/lib/security/java.policy or the corresponding file in your Java installation ) grant section:
 grant {
   permission javax.management.MBeanTrustPermission "register";
 };

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

== Compilation ==
Compile in $SOURCE/BioUML/src directory. In general you should not edit build_bdk.xml: use clean CVS version. Some settings should be fixed in build.xml file (see above). To rebuild everything use: <code>ant deploy.server</code>. 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): <code>ant plugin.all</code>

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

Clean: <code>ant clean.</code>

== 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)

[[Category:Installation]]