CTS2-LE Installation and Deployment

This section describes how to install and deploy a CTS2-LE server instance along with the navigator front-end. It has to be ensured that the system fulfils the defined prerequisites. The following steps are aligned to the recommended system environment and hence offer commands on the basis of an Ubuntu-like OS and an installed Tomcat.

Encoding

Make sure, the correct encoding for requests and responses is set. In /var/lib/tomcat7/conf/server.xml check the attribute URIEncoding in the connector tag.

<Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="8443" URIEncoding="UTF-8"/>

Allowing Encoding Slashes in URL

Add the following line to /var/lib/tomcat7/conf/calatina.properties:

org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

Setting the Resource Root and Increasing Java Heap Space

Select a directory where the terminology store instances will be located. The directory has to be specified by setting an environment variable called CTS2LE_RESOURCE_ROOT.

Since the resource root is one of the building blocks of CTS2-LE, no arbitrary manipulation of the files within the directory should be done. Only apply changes to the files which are described in this section.

In order to permanently set the environment variable, it is recommended to create a setenv.sh script in the $CATALINA_HOME/bin directory and add the following lines:

#!/bin/bash
CTS2LE_RESOURCE_ROOT=/path/to/directory
export CTS2LE_RESOURCE_ROOT

Experience has shown that increasing the heap space for tomcat positively influences the servers efficiency. Therefore, it is recommended to permanently set the environment variable CATALINA_OPTS by adding the following lines to the setenv.sh script:

#permanently increase heap space
CATALINA_OPTS="-Xms512m -Xmx900m"
export CATALINA_OPTS

It is also recommended to follow these instructions for setting environment variables system-wide.

Delivered Resources

A customer will reveice two zip-compressed archives namely:

1. load-vocabs.zip
2. WebCts2LE-resource-root.zip

Extract WebCts2LE-resource-root.zip to the destination defined by means of the environment variable CTS2LE_RESOURCE_ROOT:

unzip WebCts2LE-resource-root.zip -d $CTS2LE_RESOURCE_ROOT

Set access rights recursively:

sudo chmod -R <pattern> $CTS2LE_RESOURCE_ROOT

<pattern> has to be set accordingly, such that the server has read/write access to the resources.

Extract load-vocabs.zip to $CTS2LE_RESOURCE_ROOT/../.

unzip load-vocabs.zip -d $CTS2LE_RESOURCE_ROOT/../

Make sure the folders are structured as presented below:

/load-vocabs
/<$CTS2LE_RESOURCE_ROOT>
  /bin
     WebCts2LE.war 
     WebCts2LEStarter.sh 
  /meta
  cts2_conf.xml
  grouping.json
  setting.json

You should leave most of the directories untouched. Only adapt or execute the highlighted files as described in the section.

grouping.json

This file determines how the loaded terminologies and value sets are grouped inside the navigator. By default, the file is structured as shown below.

{
    groups: [
    {
        _id: 'csvGroups',
        children: [
           {
               name: 'ICD', relGroup: 'ICD'
           },
           {
               name: 'Example', relGroup: 'EXA'
           }
        ]
   },
   {
        _id: 'vsGroups',
        children: [
           {
               name: 'FHIR', relGroup: 'FHIR-vs'
           }
        ]
   }
   ]
}

A loaded resource either belongs to the group of code systems (_id: 'csvGroups' ) or is a child of the value set group (_id: 'vsGroups' ). The assignment of terminologies and value sets to groups is either defined in specific terminology loaders or by means of a FHIR definition file. The latter one allows for a flexible reassignment whereas for core terminologies, a change proposal has to be issued to the contact partner at Fraunhofer FOKUS. For example, the terminology loaders which import the German and English ICD and the alphabetical directory as an expansion of the German ICD individually specify the 'ICD' group membership. Groups can be hidden in the navigator by commenting out the corresponding JSON structures but reassigning a code system (e.g. any ICD related system should be grouped in a 'Diseases' section) cannot be achieved by editing the file.

The snippet above leads to the following grouping in the navigator.

Code System grouping

Value Set grouping

cts2_conf.xml

All standard terminological resources (ICD-10, LOINC, HL7v3, FHIR etc.) require the user to obtain an individual license. Therefore such terminologies are not part of the CTS2-LE distribution but have to be licenced and loaded by the CTS2-LE customer. To ease this process, the CTS2-LE distribution includes a set of "terminology loaders" which allow for an automatic integration of the most common standard terminologies into CTS2-LE. This section describes how these loaders can be activated for loading standard terminologies and value sets into CTS2-LE.

When receiving a CTS2-LE distribution, this file will comprise a reference to any terminology for which the user has obtained a license. The XML-structured file lists the available terminologies under the element vocabularies. A specific vocabulary is defined by a friendly-name and a resourceID, e.g. the Example code system will appear as the following line:

<conf>	
	<vocabularies loadAll="false" fresh="true" index="true" sigCheck="true">
		<vocabulary load="true" friendly-name="Example code system" resourceID="exa"/>
	</vocabularies>
</conf>

The friendly name is a human readable name for a terminology and may be modified by the user if he prefers a different designation. However, the attribute resourceID must not be changed as it is a system intern identifier for the terminology.

To load a vocabulary, the attribute load has to be set to true.

Mark any desired vocabulary by following this strategy (or load all terminologies by enabling loadAll in the <vocabularies> element) and save the file.

WebCts2LE.war and WebCts2LEStarter.sh

The web application archive WebCts2LE.war has to be deployed in a servlet container. Because there are further activities that come along with the deployment, a script (WebCts2LEStarter.sh) is provided.

Deployment

The delivered script WebCts2LEStarter.sh serves 2 use cases:

1. it automatically deploys the war-file
2. it faciliates the process of loading core terminologies

Before starting the script, open it and check the value of the tomcat version and tomcat home-directory.

NAME=tomcat7
CATALINA_BASE=/var/lib/$NAME

Ensure that the script is executable by running the following command:

chmod +x WebCts2LEStarter.sh

Finally, start the script by appending the war-file as an argument.

./WebCts2LEStarter.sh WebCts2LE.war

Ensure that CTS2LE_RESOURCE_ROOT is accessible from the script and that sudo is installed.

The navigator should be accessible under the following URL (port is 8080 by default):

http://<host>:<port>/WebCts2LE

Configuration

Changing the Context Path

By default, the context path of the web application is "/WebCts2LE". In order to change it, open and adapt the file $CATALINA_BASE/conf/server.xml. Change the text of the attribute path to the desired value (denoted as <path>) in the code snippet.

<Context docBase="WebCts2LE" path="/<path>" reloadable="true"/>

Please note that adaptions take effect after restart.

Determine Logging Output

Logging properties may be specified in the file $CATALINA_BASE/webapps/WebCts2LE/WEB-INF/classes/logging.properties. The following file content gives an example of writing application messages of log level INFO both to the console and a file located in $CATALINA_BASE/logs/webcts2le.yyyy-mm-dd.

	handlers = org.apache.juli.FileHandler, java.util.logging.ConsoleHandler

	############################################################
	# Handler specific properties.
	# Describes specific configuration info for Handlers.
	############################################################

	org.apache.juli.FileHandler.level = INFO
	org.apache.juli.FileHandler.directory = ${catalina.base}/logs
	org.apache.juli.FileHandler.prefix = webcts2le.

	java.util.logging.ConsoleHandler.level = INFO
	java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

Troubleshooting

• Do not run the starter script with root privileges.