This document describes how to install the software contained in the tools-service package. The following topics can be found in this document:
The Tools Service was developed using Java and will run on any platform with a supported Java Runtime Environment (JRE). The software was specifically compiled for and tested in Java version 1.8. The following commands test the local Java installation in a UNIX-based environment:
% which java
/usr/bin/java
% java -version
java version "1.8.0_101"
Java(TM) SE Runtime Environment (build 1.8.0_101-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)
The first command above checks whether the java executable is in the environment's path and the second command reports the version. If Java is not installed or the version is not at least 1.8, Java will need to be downloaded and installed in the current environment. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, the Java software can be downloaded from the Oracle Java Download page. The suggested software package is the Java Standard Edition (SE) 8, either the JDK or the JRE package. The JDK package is not necessary to run the software but could be useful if development and compilation of Java software will also occur in the current environment.
Download the tools-service package from the PDS FTP site. The binary distribution is available in identical zip or tar/gzip packages. The installation directory may vary from environment to environment but in UNIX-based environments it is typical to install software packages in the /usr/local directory and in Windows-based environments it is typical to install software packages in the C:\Program Files directory. Unpack the selected binary distribution file in the installation directory for the local environment with one of the following commands:
% unzip tools-service-0.3.0-bin.zip
or
% tar -xzvf tools-service-0.3.0-bin.tar.gz
Note: Depending on the platform, the native version of tar may produce an error when attempting to unpack the distribution file because many of the file paths are greater than 100 characters. If available, the GNU version of tar will resolve this problem. If that is not available or cannot be installed, the zipped package will work just fine in a UNIX environment.
The commands above result in the creation of the tools-service-0.3.0 directory with the following directory structure:
A README file directing the user to the available documentation for the project.
The copyright notice from the California Institute of Technology detailing the restrictions regarding the use and distribution of this software. Although the license is strictly worded, the software has been classified as Technology and Software Publicly Available (TSPA) and is available for anyone to download and use.
This is the Web ARchive (WAR) file containing the PDS Tools Service software including all dependent JAR files.
This is the Web ARchive (WAR) file containing the Web Resource Platform (WRP) Tools Service software including all dependent JAR files.
This directory contains a local web site with the program-name documentation and other configuration management related information. Just point the desired web browser to the index.html file in this directory.
This directory contains the dependent jar files for the PDS Tools Service software.
This directory contains the configuration files for the Tools Service software.
The WRP Tools Service web application is packaged as a WAR file (ts.war) and is intended for installation under a standard Java Application Server. If there was a previous installation of the Tools Service, each instance of the application should be un-deployed from the Tomcat server. This can be accomplished by deleting the applications directly (assuming the user has appropriate permission) from the $TOMCAT_HOME/webapps directory (the variable $TOMCAT_HOME may not be set in your environment, if not, replace with the absolute path to the Tomcat installation):
% cd $TOMCAT_HOME/webapps
% rm -rf ts ts.war
Alternatively, if the Tomcat Manager interface was utilized for the deployment, find the Tools Service entries in the Manager interface and select the Undeploy button for each instance to remove the applications from the server.
In order to deploy the software for either a new or upgrade installation, the WAR file is normally copied directly to the $TOMCAT_HOME/webapps directory (assuming the user has appropriate permission) or installed via the Manager interface. To copy the WAR file directly, perform the following commands:
% cd tools-service-0.3.0
% cp ts.war $TOMCAT_HOME/webapps
The configuration for the Tools Service may need to be modified based on the directory location where the tools-service package is installed. This configuration can be modified by editing the $CATALINA_HOME/webapps/ts/WEB-INF/web.xml file and updating the following parameters:
...
<servlet-name>TsInfoServlet</servlet-name>
<servlet-class>gov.nasa.jpl.wrp.ts.TsInfoServlet</servlet-class>
<init-param>
<param-name>application_conf_dir</param-name>
<param-value>/usr/local/tools-service-0.3.0/conf</param-value>
</init-param>
...
<servlet-name>TsServlet</servlet-name>
<servlet-class>gov.nasa.jpl.wrp.ts.TsServlet</servlet-class>
<init-param>
<param-name>application_conf_dir</param-name>
<param-value>/usr/local/tools-service-0.3.0/conf</param-value>
</init-param>
...
Once this step is complete, the application is ready for operation. Verify a successful installation by accessing the component from your favorite web browser at the end point http://localhost:8080/ts.
The WRP Tools Service comes configured to access the following command-line tools:
In order to access these tools in the user's local environment, the path variable in each of the configuration files (found in the conf directory of the distribution) need to be modified to reference the tool executable in the user's local environment (these tools need to be installed separately). The configuration file for the Transform Tool (transform.conf) is displayed below as an example:
type = executable
version = 1.7.0
description = PDS4 Transform Tool
path = /usr/local/transform-1.7.0/bin/transform
arguments = -t <target> [-f=<format-type>] [-o=<outdir>] [-n=<index>] [-<options>(a|O)] [-d=<datafile>]
success_exit_status_codes = 0
In order to add a new tool to the service, create a configuration file like the one above detailing the tools location and arguments. More details regarding the addition of new tools will be supplied at a later date.
The Transform Tools Service web application is packaged as a WAR file (tools-service.war) and is intended for installation under a standard Java Application Server. If there was a previous installation of the Transform Tools Service, each instance of the application should be un-deployed from the Tomcat server. This can be accomplished by deleting the applications directly (assuming the user has appropriate permission) from the $TOMCAT_HOME/webapps directory (the variable $TOMCAT_HOME may not be set in your environment, if not, replace with the absolute path to the Tomcat installation):
% cd $TOMCAT_HOME/webapps
% rm -rf tools-service tools-service.war
Alternatively, if the Tomcat Manager interface was utilized for the deployment, find the Transform Tools Service entries in the Manager interface and select the Undeploy button for each instance to remove the applications from the server.
In order to deploy the software for either a new or upgrade installation, the WAR file is normally copied directly to the $TOMCAT_HOME/webapps directory (assuming the user has appropriate permission) or installed via the Manager interface. To copy the WAR file directly, perform the following commands:
% cd tools-service-0.3.0
% cp tools-service.war $TOMCAT_HOME/webapps
The configuration for the Tools Service may need to be modified, if needed. This configuration can be modified by editing the $CATALINA_HOME/webapps/tools-service/WEB-INF/web.xml file and updating the following parameters:
...
<context-param>
<param-name>tools.service.url</param-name>
<param-value>http://localhost:8080/ts/</param-value>
</context-param>
...
<context-param>
<param-name>tempfile.rootdir</param-name>
<param-value>/tmp</param-value>
</context-param>
...
Once this step is complete, the application is ready for operation. Verify a successful installation by accessing the component from your favorite web browser at the end point http://localhost:8080/tools-service.
