v1.2.0

Installation and Setup of Infrastructure Components

Note:  If you have Windows User Access Control turned on, you may need to disable it in order to complete the installation properly.

...

NOTE: we have created a common, publicly accessible Apelon DTS instance for maintaining a central set of concepts for use by the OpenCDS community.  Software to access this is included in the OpenCDS source distribution.

Install Java SE SDK version 7

1. Download appropriate 32-bit or 64-bit Java SE SK from http://www.oracle.com/technetwork/java/javase/downloads/index.html
2. Run executable, install using default options
   • You can use a non-default installation directory if desired
3. Windows: Control Panel → System → Advanced → Environment Variables → System Variables
   
   1. Set JAVA_HOME to Java SE SDK location
      
      1. e.g., C:\Program Files\Java\jdk1.7.0_45.jdk
   2. Add %JAVA_HOME%\bin to path
      1. In this example, was added to beginning of path
4. Linux/Mac:
   1. Add JAVA_HOME as an environment variable to the shell environment.
      1. bash/linux: export JAVA_HOME=/path/to/jdk
      2. bash/mac: export JAVA_HOME=`/usr/libexec/java_home -v 1.7`
   2. Add $JAVA_HOME/bin to PATH
      1. bash: export PATH=$PATH:$JAVA_HOME/bin

Install Tomcat

1. Download latest Tomcat
   1. Windows:
      1. Download “32-bit/64-bit Windows Service Installer” from relevant download page at http://tomcat.apache.org

      2. OpenCDS has been tested using both Apache Tomcat versions 6 and 7, and it can be built to run on either, but the public download is built for Tomcat version 7.

         1. Note:  OpenCDS will not deploy on JBoss without making some changes to the included libraries
      3. Accept defaults

      4. Installation directory may be changed if desired

      5. Set Tomcat Administrator Login to something secure

         1. You may even prefer to remove the administrator login if you have physical access to the server.

      6. Control Panel → System → Advanced → Environment Variables → System Variables

         1. Set CATALINA_HOME to, e.g., “C:\Program Files\Apache Software Foundation\Tomcat 6.0”

         2. Add %CATALINA_HOME%\bin to Path

            1. In this example, was added to beginning of Path
   2. Linux/Mac:
      1. download the tar.gz package, and unpack it to the desired location.
      2. Set CATALINA_HOME to the location of the Tomcat folder
         1. export CATALINA_HOME=/path/to/tomcat
      3. Add CATALINA_HOME/bin to PATH
         1. export PATH=$PATH:$CATALINA_HOME/bin

OpenCDS Configuration

Externalized OpenCDS configuration options are stored in the locations below:

Windows:

•  %HOME%\.opencds\opencds.properties

  NOTE: If OpenCDS is running on tomcat as a service on a Windows system, the configuration will likely have to live at the root (i.e., C:\.opencds\opencds.properties), as there is no default user.

Linux/Mac:

• $HOME/.opencds/opencds.properties

  NOTE: If installed as a service started at boot, the configuration must live under the $HOME (as defined in /etc/passwd) of the user that starts the container.  E.g., if OpenCDS is running on tomcat as run by the system init scripts, and is run by the tomcat user, the properties must live under the tomcat $HOME as defined in /etc/passwd–typically /home/tomcat.

This file must contain the first two lines below.  The third line is options, if logging is desired.

...

• knowledge-repository.type may be either of the two following values:

  • SIMPLE_FILE

  • CLASSPATH

• knowledge-repository.path is the absolute or relative path to the configuration, depending upon which type is chosen (above).
  • Example configurations for SIMPLE_FILE may include:
    • /var/lib/opencds/resources_v1.1/
    • /home/opencds/config/resources_v1.1/
    • $HOME/.opencds/config/resources_v1.1/
    • etc.
  • The path for the CLASSPATH type is relative to the classpath of the running JVM (e.g., Tomcat).
    • resources_v1.1/
• log4j.logfile is the location used by OpenCDS to write the logs.  This line is optional.  Typical values may include:
  • /var/log/opencds/opencds.log
  • $HOME/.opencds/logs/opencds.log

PLEASE NOTE: The paths provided in opencds.properties on a Windows-based system must have all backslashes escaped or the system will not start properly.  For example, if your repository path is at the root folder in C:, e.g., C:\opencds-kr\resourceAttributes, the path configured for knowledge-repository.path must be either C:\\opencds-kr\\resourcesAttributes or C:/opencds-kr/resourcesAttributes (note the forward-slashes).

Install OpenCDS Sample Knowledge Repository

Filesystem-based Method

1. A sample knowledge repository is distributed with the OpenCDS deployment file (the 'war').
2. Download opencds-knowledge-repository-data.zip from the OpenCDS website | Members | Binary Downloads | at http://develop.opencds.org/OpenCDSDemo/latest/opencds-knowledge-repository-data.zip
3. Unzip it to the location specified in the OpenCDS Configuration discussion above.
   1. The location must be on a filesystem visible to the running instance of Tomcat.

Jar-based Method

NOTE: This option is for developers and advanced users.

1. A test repository is included in the war, and may be updated with custom repository elements by following the standard procedures for manipulating jar files.
2. NOTE: Developers may update their local copies of the codebase to automatically build the war with a custom repository.  However, please do not commit this to the repository.

Install OpenCDS RunTime WAR file

1. Download latest OpenCDS RunTime war file from the OpenCDS website | Members | Binary Downloads | OpenCDS11
   1. http://www.opencds.org/Members/BinaryDownloads/OpenCDS11.aspx
2. Rename the file to “opencds-decision-support-service.war”
   1. (this step is not absolutely necessary, but will make your runtime match other instructions in our documentation, and so it is probably a good idea unless you know what you are doing).
3. Stop Tomcat
4. Copy the opencds-decision-support-service.war file into the %CATALINA_HOME%\webapps folder
5. Restart Tomcat

Test the Installation

1. Open a web browser on the same machine that you installed Tomcat on, and go to
   1. http://localhost:8080/opencds-decision-support-service/evaluate?wsdl
   2. The browser should display the WSDL.
   3. If it is installed on a different machine, or you changed the default port to something different than 8080, make the appropriate changes to the URL above.
2. To interact with the DSS, a convenient program to use for testing and demo is the oXygen XML editor (http://www.oxygenxml.com).  We use the Academic/Non-Commercial version, and a free trial license is available at http://www.oxygenxml.com/register.html.
3. Other tools are available, and some are open-source, such as SoapUI at http://www.soapui.org , or the Firefox addon at https://addons.mozilla.org/en-US/firefox/addon/soa-client, for those of you who want to experiment.
4. You can also use the open-source MirthConnect software to test rules, as well as in a production environment, because it includes support for web services.  The software can be found at http://www.mirthcorp.com/products/mirth-connect.  We have some sample channels available in the Demo folder.
5. If you are using oXygen, go to Tools → WSDL SOAP Analyzer → Saved SOAP request, and use the sample .wssc files available from the OpenCDS website | Members | Binary Downloads | OpenCDS11.  Hitting the "Send" button will interact with the DSS.  Note that a base64 converter for reading base64 payloads is available at http://ostermiller.org/calc/encode.html or http://www.opinionatedgeek.com/DotNet/Tools/Base64Encode/default.aspx

Document Version History

(Duplicated/reversed from original document.  Document above has minor edits from the original versiondocument–included for historical purposes.)

• 5/21/2013

  • Removed developer setup, and Guvnor setup instructions to create new RunTime Installation Guide

• 1/11/2013

  • Updated to reflect Drools 5.5, Designer 5.4

• 11/14/2012
  • Major update by David Shields to reflect latest versions of all components, including Drools 5.4, JBPM Designer 5.3, and JBoss 7.1.x

• 12/17/2011

  • Updated by David Shields to include information on extended default timeout for JBoss AS 7.0.2

• 12/16/2011
  • Updated by David Shields to include alternate installation paths, 2.0  version of JBoss Designer, alternate ports for JBoss, and availability of OpenCDS 1.0 binaries.

• 11/29/2011

  • Updated by David Shields to include solution to failed installation of JBoss Application Server in a path including “Program Files (x86)”.

• 11/16/2011
  • Updated by Kensaku Kawamoto to include preliminary Guvnor/Designer installation instructions and to make additional note regarding Tortoise SVN

• 11/10/2011

  • Updated by Kensaku Kawamoto to note need to use latest Tortoise SVN version

• 11/9/2011

  • Updated by Kensaku Kawamoto to include use of SilkSVN for 32-bit OSs as well

• 11/8/2011

  • Updated by Kensaku Kawamoto, with verification on 32-bit and 64-bit Windows OSs

  • Use of Drools 5.3.0 instead of 5.2.0 

• 8/28/2011

  • Created by Kensaku Kawamoto based on configuration instructions for OpenCDS alpha release
    • Changes include:
      • Use of Drools and Guvnor 5.2 instead of 5.1.1
      • More information on 64-bit OS configuration
      • Use of newest releases of software components

...