Release 1.0 Installation guide

NIST FHIR(R) Toolkit December 2019 Release (version 1.0)

This release

This release is packaged as a ZIP (asbestos.zip) of a full Tomcat installation with the components of FHIR Toolkit already installed. There are two components not included, XDS Toolkit and HAPI FHIR server. These components are required but many users will already have them running on their system. If you do not have them already we provide directions for getting and installing them.

Once asbestos.zip is downloaded and unzipped, there are two versions of the installation documentation you can use: this wiki page and the top level README.txt file in the ZIP. They cover mostly the same material but from slightly different perspectives.

Asking questions

The preferred approach is to use the ihe-mhd-implementors@googlegroups.com mailing list.

Requirements

These instructions assume your system is capable of running Apache Tomcat Server Version 9.0.26. This means Java 8 should already be installed and accessible through your system environment. It also assumes the following system ports:

9705 Tomcat Shutdown port
9709 AJP
9743 TLS (reserved for future)
9760 HTTP

are all available and free to be used by the FHIR Toolkit's Tomcat CATALINA_BASE. The CATALINA_BASE environment variable specifies location of the root directory of the "active configuration" of Tomcat. See /tomcat/RUNNING.txt for more details on CATALINA_BASE. Each type of Toolkit (FHIR, XDS) makes use of a dedicated CATALINA_BASE.

Background on Tomcat/Catalina_Base

Most users of Tomcat are familiar with the sub-directories within Tomcat: bin, conf, logs, temp, webapps etc. The scripts in bin are used to start/stop Tomcat. When Tomcat starts, all the WAR files in webapps/ are launched. FHIR Toolkit uses a more advanced configuration of Tomcat where there are multiple Catalina_Bases - independent areas of Tomcat that can be started/stopped independently. They share common bin/, logs/, temp/ directories and have their own bin/, conf/, and webapps/. These common parent directories are referred to as Catalina_Home. Because each Catalina_Base has its own conf/server.xml, different port numbers and security configurations are used in each Catalina_Base. FHIR Toolkit is organized around this multi-Catalina_Base structure. FHIR Toolkit comes with two bases located in the Toolkits/ directory: FhirToolkit and XdsToolkit. FhirToolkit/ comes loaded with the components needed to run the FHIR Toolkit. XdsToolkit/ can optionally be used to house XDS Toolkit and HAPI FHIR (user installs these). The Toolkits/ directory also comes with an ExternalCache/ directory which is a shared External Cache for XDS Toolkit and FHIR Toolkit.

Contents of asbestos.zip

The zip file contains a Tomcat Application Server bundled with the FHIR Toolkit web application. It is configured to run on HTTP port 9760.

NOTE: The zip file does NOT include XDS Toolkit or the HL7 HAPI FHIR distributions. For information on installing them if you do not already have them on your system, please see below:

General XDS Toolkit Installation instructions can be found at: https://github.com/usnistgov/iheos-toolkit2/wiki/installing The following instructions demonstrate how to install an XDS Toolkit release in to the provided Toolkit Catalina base shell. A Catalina base shell is only the configuration to start Tomcat but without the XDS Toolkit Java Web Application Archive (WAR) file. The XDS Toolkit Catalina base shell is located in the /tomcat/Toolkits/XdsToolkit folder. Download an XDS Toolkit release (WAR file) from the Releases Page: https://github.com/usnistgov/iheos-toolkit2/releases. You must use version 7.3.0 or later. Rename the downloaded war file to "xdstools.war". This will simplify the web application context reference. Place the downloaded xdstools.war into the /tomcat/Toolkits/XdsToolkit/webapps folder Start Tomcat for XdsToolkit

How to Setup\Install

Unzip the contents to a folder of your choice. The full path of this folder will be referred to as "<installation-directory>". In the examples below, you will have to replace the token with the directory location of the folder where the zip file was extracted.

Installation

Most of the installation of FHIR Toolkit was done when you unpacked the asbestos.zip file. FHIR Toolkit depends on XDS Toolkit and HAPI FHIR. You either have them already on your system so you just need to update the configuration or you need to install them and update the configuration.

Installing XDS Toolkit

Download from https://github.com/usnistgov/iheos-toolkit2/releases (version 7.3.0 or later) and follow the installation instructions for that package. We recommend using the directory tomcat/Toolkits/ExternalCache for your external cache (used by both XDS Toolkit and FHIR Toolkit). But XDS Toolkit can be installed on a different machine.

Installing HAPI FHIR

Download from https://github.com/usnistgov/asbestos/releases/download/0.1/hapi-fhir.zip and expand the zip. If you are installing inside the asbestos package, unzip into the directory tomcat/Toolkits/XdsToolkit/webapps/fhir.
Edit the file WEB-INF/classes/hapi.properties. The properties server_address and server.base (both at the top of the file) must be updated to match your installation. We recommend not using localhost in server_address since this will limit access to the local machine. Once running in tomcat test the installation by opening server_address value in a browser and the HAPI home page should appear. If you follow our recommendation of installing HAPI as fhir.war then the only updates to this file are the hostname and port specified in server_address.

You can use a different installation of HAPI FHIR. But it must be R4 compliant. We include in the above download the version we used in developing FHIR Toolkit.

Configuring FHIR Toolkit - edit service.properties

In Toolkits/FhirToolkit/conf there is a file service.properties which must be edited. This is the master configuration file for the tool. The overall toolkit is made up of 4 components: XDS Toolkit server, HAPI FHIR server, Proxy server, and Test Engine server. Each must know the base address of the others. This file contains those base addresses.

Testing this configuration - once the tomcat(s) are running, launch the user interface from a browser

http://localhost:9760

At the top of the home page is a section labeled Self Test. It will report on the reach-ability of each component. It can be repeated at any time using the Run link.

Starting/Stopping

We include two sets of instructions for starting and stopping FHIR Toolkit: a fully automated script and a fairly manual approach. First, what has to be accomplished? HAPI FHIR and XDS Toolkit must be started before FHIR Toolkit. Our scripts handle this IF you have installed HAPI FHIR and XDS Toolkit in this CATALINA_HOME. If you run them on a separate Tomcat then this sequencing is up to you.

Automated approach

Our fully automated script handles this procedure:

If Toolkits/XdsToolkit/webapps is not empty then start XdsToolkit CATALINA_BASE on port 9770 (default).
Start FhirToolkit CATALINA_BASE on port 9760 (default).

Start script - tomcat/bin/start.sh (or start.bat) (this is different than the usual tomcat startup.sh)
Stop script - tomcat/bin/stop.sh (or stop.bat) (this is different than the usual tomcat shutdown.sh)

Manual approach

On Windows

Set CATALINA_HOME to the Tomcat directory

 SET CATALINA_HOME=<installation-directory>\tomcat

Set the XDS Toolkit Catalina Base

 SET CATALINA_BASE=%CATALINA_HOME%\Toolkits\XdsToolkit

Start Tomcat

 %CATALINA_HOME%\bin\startup.bat

Shutdown Tomcat

 %CATALINA_HOME%\bin\shutdown.bat

On *nix (MAC and Linux)