Tomcat configuration

To deploy Tav4SB Web service you'll need to setup the Tomcat manager. Add manager role and user in that role to the tomcat-users.xml configuration file, e.g.:

<tomcat-users>
  ...
  <role rolenmae="manager"/>
  <role rolename="tomcat"/>
  <user username="admin" password="TopSecretPwd" roles="tomcat,manager"/>
  ...
</tomcat-users>

(You can find this file in /etc/tomcat6/ if you have installed Tomcat via APT package manager on Ubuntu or in /opt/local/share/java/tomcat6/conf/ if it was Mac OS X and MacPorts.)

Start or restart you're Tomcat instance and make sure the manager works. You can test it by going to the http://localhost:8080/manager/html URL (adjust port and host name accordingly) and logging in. (Start with sudo /etc/init.d/tomcat6 [re]start in Ubuntu and in most Linux distributions, sudo tomcatctl [re]start in Mac OS X.)

Computational tools

There is an generic, purely Java worker which ads two numbers to test the server so you don't need anything extra to set up the backbone. Optionally, install any of the following computational tools:

• Mathematica >=7.0 [12],
• PRISM ==4.0.x [11],
• SBML ODE Solver ==1.6 [10].

If you're setting up a distributed installation, then install these only on servers at which you would like to run them.

Configure system

Set up few environmental variables. Template file is available in:

TAV4SB_HOME/tav4sb_env

You can copy'n'edit it and source it in your ~/.bash_profile/~/.bashrc/~/.profile file by putting something like this in it:

if [ -f ~/tav4sb_env ]; then
    . ~/tav4sb_env
fi

Make sure that:

• TAV4SB_{CLIENT,SERVER}_ROOT indicate main folders where the source code for client and server sub-projects reside,
• TAV4SB_LOG_ROOT exists and you have permissions to write to it,
• TAV4SB_{QUEUE,TOMCAT}_HOSTNAME name hosts (name or IP) with queue and Web server installed; if you haven't install queue, just name a host where it will be run,
• optionally, {PRISM,MATHEMATICA}_HOME point to respective folders; you can ignore these if you're not planning to run these tools on a server at which you're currently installing source (localhost in particular).

Configure server

Copy'n'edit configuration properties for the server:

cp ${TAV4SB_SERVER_ROOT}/{dev,local}.properties

You can name the copy differently, but then you must adjust the server's POM file as well (it's ${TAV4SB_SERVER_ROOT}/pom.xml) [6].

Make sure that:

• tomcat.*, i.e. Tomcat configuration, is set appropriately, including the tomcat.manager.url right port (8080 by default) and Tomcat manager user name and password;
• optionally, if you won't be using helper queue sub-project on localhost (see below), broker.name and broker.url are pointing to your queue installation;
• thread.number corresponds to your hardware configuration;
• smtp.*, email.*, i.e. mail configuration, is filled in with details of you favorite mail host and account;
• optionally, computational tools details, such as prism.classpath are set accordingly to how you've installed them.

Install external libraries

Some computational tools will require libraries which are not available in Maven repositories. For instance, Mathematica's connector library - JLink [13], must be installed manually. So, if you plan to use Mathematica worker you should already have the MATHEMATICA_HOME environmental variable set up. Either way, use the Bash helper script to install external libraries:

${TAV4SB_SERVER_ROOT}/main/scripts/install_libs.sh

.

Note: If this is the first time you're using a maven command at the machine you're installing the Tav4SB project, then you'll see a lot of downloading - that's fine. This is going to repeat during the build etc, so just be patient.

Build server

If you want to build everything, just run the Bash helper script:

${TAV4SB_SERVER_ROOT}/mvn_build

This build excludes tests so even if you won't use all of the available workers the build should run smoothly. If you want to build or test specific workers then enter appropriate ${TAV4SB_SERVER_ROOT}/logic subfolder and run mvn clean install (add -Dmaven.test.skip=true to skip tests).

Note: if it's the first build with Maven (a lot of downloading going on), then it's a good moment to grab a drink or a cookie - it's gonna be a while.

Test and pack workers

To test selected workers, e.g. add and prism worker, run:

${TAV4SB_SERVER_ROOT}/mvn_test add prism

Passed parameters are names of sub-projects in ${TAV4SB_SERVER_ROOT}/logic. These are usually smoke tests, which allow you to check if you have configured everything properly. To see the results, check out the ${TAV4SB_LOG_ROOT} folder.

To pack workers into JARs [14], e.g. add and prism worker, run another helper script:

${TAV4SB_SERVER_ROOT}/mvn_pack add prism

.

Note: the asynchronous register is always packed when using that script.

Run queue and workers

To run everything locally, e.g. queue with add and prism workers and the register, use:

${TAV4SB_SERVER_ROOT}/main/scripts/dev_startup.sh add prism register

This script optionally takes names of selected workers as parameters (actually, unique prefixes of server sub-projects). If none given, then all, originally available, workers are run. Feel free to look inside of this simple script for any custom startup adjustments.

Attention: if the queue is run for the first time with help of Maven, then downloads may cause the situation at which workers are started before the queue. This is bad. It will probably end up in an error. After everything has been downloaded just run the script again and if that doesn't help (you're fishing for INFO: ActiveMQ JMS Message Broker (...) started message before Running: java -jar ... messages) adjust the TAV4SB_QUEUE_STARTUP_SEC environmental variable.

In the ${TAV4SB_SERVER_ROOT}/main/scripts/ folder you'll find other helper scripts to automatize the startup and restart of queue and workers, including the sysinit.sh script for Linux autostart.

Note: system startup script was tested only under Ubuntu and may require adjustments for distributions not based on Debian, like Gentoo or Red Hat/Fedora, e.g. sourcing the functions library (. /etc/rc.d/init.d/functions) and killproc instead of kill.

Test and deploy Web service

To build and test the webservice project just go to its folder, build it (queue, register and workers have to be up for tests to pass) and test with selected workers, for instance:

cd ${TAV4SB_SERVER_ROOT}/webservice
mvn -Dtest=AddTest,PrismTest clean install

The other test classes for workers are MathematicaTest and OdeSolverTest. Of course, you can build and test separately; also, cleaning before build is optional, but recommended.

Note: if you notice some problems with unique ID generation try to run the test again.

Now, build and deploy the WAR [15] file with the Tav4SB Web service:

${TAV4SB_SERVER_ROOT}/webservice/mvn_tomcat deploy

Test the WSDL file in your browser by going to the http://localhost:8080/tav4sb/services?wsdl URL (adjust host name, port number or even deploy path accordingly if you have had set those up differently).

Adjust the WSDL

If everything went smoothly you're watching a WSDL file right now. You have also probably noticed that there are much too much messages, ports and bindings available in it. It's not required but just to keep order you may like to remove/comment them out. Also, you may like to adjust service name, namespaces and whatever suits you. To do all that you have to edit the WSDL file which is manually-managed and available at:

${TAV4SB_SERVER_ROOT}/webservice/src/main/webapp/WEB-INF/wsdl/Tav4SBService.wsdl

After changing WSDL, don't forget to rebuild, test and redeploy the Web service.

Configure client

Copy'n'edit configuration properties for the client:

cp ${TAV4SB_CLIENT_ROOT}/{dev,local}.properties

Again, you can name the copy differently, but then you must adjust the client's POM file (${TAV4SB_CLIENT_ROOT}/pom.xml) [6].

Make sure that wsdl.url points to the hosted Tav4SB WSDL file and that {workflows,models}.url point to where you'll host models and workflows files. If you haven't installed a Web server, hosting files via file system (default) will only work if you run workflows from the same machine at which you have installed the client source code.

Note: on Ubuntu hosting models and workflows is as easy as installing apache2 package and creating the tav4sb symbolic link to the ${TAV4SB_CLIENT_ROOT}/target/deploy folder in the default's site RootDirectory folder (usually /var/www; following symbolic links and showing directories indices should be set on by default).

Build and use the client

Building the client sub-project boils down to filtering resources, which are located in the ${TAV4SB_CLIENT_ROOT}/src/main/resources folder. To do that run a helper script:

${TAV4SB_CLIENT_ROOT}/mvn_build

Afterwards you should have the ${TAV4SB_CLIENT_ROOT}/target/deploy folder available and you should be able to browse it at given {workflows,models}.url URLs.

Now, launch Taverna Workbench and, for instance, if you have a running prism worker, open the pmc_comp.t2flow from URL (workflows.url) and run it. That's it.