R-T Installation Guide - (v2.x and up)

Owned by Phillip Warner
Last updated: Jan 25, 2017 by David Shields
4 min read

Alternatively:

v2.0.x

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.

We also have reports that OpenCDS has been successfully installed on Linux and Macintosh machines, by users who are experts in those environments.

Also note:  these instructions do not encompass setting up an Apelon DTS terminology service instance.  Setting up such an instance is not required for use of OpenCDS.  Documentation on setting up an Apelon DTS instance can be found at http://apelon-dts.sourceforge.net/.

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

For full details on OpenCDS configuration and the tooling to support an active installation, please refer to: Configuring OpenCDS (v2.x and up)

Install OpenCDS Sample Knowledge Repository

Filesystem-based Method

  1. A sample knowledge repository is distributed alongside the OpenCDS deployment file (the 'war').
  2. Download opencds-knowledge-repository-data.zip from Releases.

  3. Unzip the contents of the downloaded file to the location specified in the opencds.properties file (see OpenCDS Configuration above).

    1. The location must be on a filesystem visible to the running instance of Tomcat.
    2. The location specified in the configuration must contain the configuration folders (e.g., conceptDeterminationMethods, knowledgePackages, etc.).

Store-based Method (BDB)

  1. Create the folder specified in the opencds.properties file (see OpenCDS Configuration above).
  2. After starting Tomcat (and hence OpenCDS; see RuntimeWar below), configuration can be loaded via the Configuration Front-end Tooling (REST Client) (the --transfer option is useful in this context).

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 this Wiki at:
    1.  Releases
  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 on the Tomcat Server you installed for OpenCDS
  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.

    1. Example testing using Oxygen

      To test the service, download the bounce WSSC file from the OpenCDS website.  This request sends information to OpenCDS. OpenCDS processes the request and sends information back to you (hence 'bounce').  Note:  you must use the URL for your own installed copy of OpenCDS, e.g.: http://localhost:8080/opencds-decision-support-service/evaluate

      Open the SOAP Analyzer > 'Saved SOAP Requests' tab > enter the location of the WSSC file. When the WSDL SOAP Analyzer appears, a request with all needed information will be ready to send. Hit the 'Send' button, after a brief period the response section will be populated with a response. Tada, it works! Magic! Your first OpenCDS request!

  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