wiki:PipelineWS/SetupGuide
Last modified 9 years ago Last modified on 10/19/09 23:54:16

Pipeline WS Setup Guide

Introduction

This guide is intended to assist in the installation and configuration of the DAISY Pipeline WS application in a server environment. It will cover the following information:

  • how to install and configure Apache Tomcat to prepare the server environment
  • how to install the Pipeline Core instance used to execute Pipeline jobs
  • how to deploy and configure the Pipeline WS application

Java Runtime Environment

The Pipeline, Pipeline WS and Tomcat are all Java-based software and they obviously depend on the installation of a Java Runtime Environment (JRE). You need to install version 5.0 or above, you can download it from the Java.com web site.

Apache Tomcat

Note: The Pipeline WS is a web application which relies on the Java Servlet technology. It should theoretically be deployable to any servlet container, but it has only been tested with Apache Tomcat and we recommend it for production environments.

Installing Tomcat

You need to install Apache Tomcat version 6 or above, binary distributions are available from the Tomcat 6 download page. On Windows, we recommend to use the Windows Service Installer distribution to install Tomcat as a system service (enabling startup and shutdown via the Service Manager interface).

From now, you can try to start tomcat (e.g. via the Services manger on Windows, or using the startup.sh script on Mac or Linux) and the Tomcat welcome page should be available at http://localhost:8080/. If Tomcat doesn't launch properly, see the following troubleshooting sections.

Problem with Tomcat 6 as a Windows Service with Java 6

On Windows, after having installed Tomcat 6 as a Windows Service and if you are running Java 6, you may not be able to start Tomcat if some environment variables are not properly set. As mentioned in the Sun forums, the Tomcat service relies on the {{{msvcr71.dll}} library and Windows must be able to find it to launch the service succesfully.

A solution would be to move the msvcr71.dll file to the Windows\system32 directory, but a better solution is to correctly edit PATH system environment variables:

  1. Go to the Control Panel > System > Advanced system settings > Environment Variables
  2. Under "System variables" use the "Edit…" button.
  3. Add the JRE binary directory to the PATH variable (e.g. PATH=%SystemRoot%\system32; ... ;C:\Program files\Java\jre6.0_06\bin)
  4. Restart Windows

Launching Tomcat on Windows with a 64bit Java installation

Tomcat is by default installed with 32bit launcher executables, and it therefore fails to start if you try to execute it with a 64 bit Java runtime.

To work around it, you must download 64 bit versions of the Tomcat executables from the Tomcat source code repository (select the repository branch corresponding to your Tomcat version), and copy it to the $TOMCAT_HOME/bin directory to replace the 32 bit executables.

Configuring Tomcat

Memory Settings

It is recommended to increase the default initial and maximum heap size of the Java virtual machine running Tomcat. To do so, add the following arguments to the JVM startup options:

	-Xms512m
	-Xmx512m

These JVM startup options can be added by manually editing the Tomcat startup script (e.g. $TOMCAT_HOME/bin/catlina.sh) or on Windows via the Tomcat Startup Options graphical utility accessible from the Start menu.

Pipeline Core

The Pipeline WS needs a standalone DAISY Pipeline installation to launch new jobs. We recommend the use of the DAISY Pipeline Core binaries which can be downloaded as a ZIP archive from the DAISY Pipeline project page. The Pipeline WS requires a recent version of the Pipeline which has not been released at the time of writing this guide. You can compile the latest binaries from the source or contact the Pipeline developers to get a recent build. Unzip the archive to a directory of your choice.

Pipeline WS

Deploying the Pipeline WS application to Tomcat

The environment must now be fully configured, and you're ready to deploy the application to Tomcat.

First, open the Tomcat manager web application at http://localhost:8080/manager/html in your browser.

Note: you can edit Tomcat administrator user names and password by manually editing the configuration file $TOMCAT_HOME/conf/tomcat-users.xml.

Scroll down to the "Deploy" section, and use the "WAR file to deploy" form to upload the pipeline-ws.war file, then press the "Deploy" button.

During the deployment, Tomcat copies the pipeline-ws.war web archive to the $TOMCAT_HOME/webapps/ directory, and unzips it in the pipeline-ws directory. Then it tries to start the Pipeline WS application ; however, the startup should fail because the application is not properly configured yet.

Configuring the Pipeline WS

In order to start successfully, the Pipeline WS needs to be configured with the path to the Pipeline Core instance it should use to execute new jobs.

This path is configured in a properties file within the Pipline WS application directory: $TOMCAT_HOME/webapps/pipeline-ws/WEB-INF/classes/settings.properties. In this file, set the pipeline.dir property to the location of your Pipeline Core directory. Other properties can be set to refine the configuration of the Pipeline WS.

Here is an example of a settings.properties file. Lines starting with '#' are commented out.

	pipeline.dir=/Users/MyUser/Desktop/pipeline-20091020/
	#execution.maxpoolsize=10
	#execution.timeout=60000
	#execution.timeoutMonitoringInterval=2000
	#creation.timeout=10000
	#creation.javacmd=java

You may want to keep a backup of this settings.properties file in a locaiton of your choice in case it is overwritten in a future deployment.

After having edited this settings properties, it is recommended to restart Tomcat. You should then be able to access the Pipeline WS at http://localhost:8080/pipeline-ws/ws/pipeline and the WSDL at http://localhost:8080/pipeline-ws/ws/pipeline?wsdl.

Troubleshooting a failed launch with the Tomcat log files

The Tomcat log files are located in the $TOMCAT_HOME/logs directory. The Pipeline WS specific log file is named pipeline-ws.log.

You can have a look at these log files to get a hint on why the deployment failed, and possibly report to the Pipeline developers.

If the log contain exceptions with the message "Port already in use: 1099", it means that a ghost Pipeline Core process prevents remote binding of the Pipeline WS to the Pipeline Core. It should be fixed by restarting Tomcat.

Redeploying a new version of the Pipeline WS

You can undeploy the application via the Tomcat Manager application: go to the application row in the Applications table and use the "Undeploy" link.

For a cleaner undeploy, you can also stop Tomcat, go to the $TOMCAT_HOME/webapps/ directory and remove the pipeline-ws.war file and pipeline-ws/ directory.

Then, you can redeploy the application with the same steps described in the previous "Deploying the Pipeline WS application to Tomcat" section.