Pipeline 1 Web Service Setup Guide

Pipeline 1 Web Service Setup Guide

This guide is intended to assist in the installation and configuration of the DAISY Pipeline 1 WS application in a server environment.

Menu

Java Runtime Environment

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

Apache Tomcat

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

Installing Tomcat

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

You can now 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 there may be a problem with Tomcat 6 as a Windows Service with Java 6. 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. The Tomcat service relies on the {{{msvcr71.dll}} library and Windows must be able to find it to launch the service successfully. A solution would be to move the msvcr71.dll file to the Windows\system32 directory, but a better solution would be to correctly edit PATH system environment variables:

  1. Go to Control Panel > System > Advanced system settings > Environment Variables
  2. Select Edit under System variables
  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 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 this, you should 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 1 installation to launch new jobs. It should be a recent version. 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 should be fully configured, and you’re now ready to deploy the application to Tomcat:

Open the Tomcat manager web application at ​http://localhost:8080/manager/html in your browser. You can edit Tomcat administrator user names and your 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.warfile.

Press the Deploy button. During 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 uses 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.

You may want to keep a backup of this settings.properties file in a location 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 understand why the deployment might have failed, and you could report this to the Pipeline developers.

If the log contains 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. This can be fixed by restarting Tomcat.

Redeploying a new version of the Pipeline WS

You can un-deploy the application via the Tomcat Manager application: go to the application row in the Applications table and use the Undeploy link.

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

You can then redeploy the application with the same steps described above.

Tags: Pipeline 1