Skip to content

Replace XDS Toolkit with another version

Jump to bottom
Sunil Bhaskarla edited this page Dec 4, 2019 · 1 revision

Replace XDS Toolkit with another version

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. The XDS Toolkit Catalina base is located in the <installation-directory>/tomcat/Toolkits/XdsToolkit directory.

  • You may want to backup your existing ExternalCache directory and start with a clean ExternalCache directory.
  • You must use an XDS Toolkit that is compatible with FHIR Toolkit.
  • Download an XDS Toolkit release (WAR file) from the Releases Page: https://github.com/usnistgov/iheos-toolkit2/releases
  • Rename the downloaded war file to xdstools.war. This will simplify the web application context reference.
  • Place the downloaded xdstools.war into the <installation-directory>/tomcat/Toolkits/XdsToolkit/webapps directory
  • Start Tomcat for XdsToolkit

On Windows

Starting XDS Toolkit
     REM Set CATALINA_HOME to the Tomcat directory
     SET CATALINA_HOME=<installation-directory>\tomcat
     REM Set the XDS Toolkit Catalina Base
     SET CATALINA_BASE=%CATALINA_HOME%\Toolkits\XdsToolkit

     REM Start Tomcat
     %CATALINA_HOME%\bin\startup.bat

On *nix

Starting XDS Toolkit
     # Set CATALINA_HOME to the Tomcat directory
     export CATALINA_HOME=<installation-directory>/tomcat
     # Set the XDS Toolkit Catalina Base
     export CATALINA_BASE=$CATALINA_HOME/Toolkits/XdsToolkit

     # Start Tomcat
     $CATALINA_HOME/bin/startup.sh

Configure XDS Toolkit Properties

  • Open a Web browser to http://localhost:9770/xdstools and dismiss any alerts or pop-ups related to External Cache.
  • At the top left of the window is a link labeled Toolkit Configuration. Open it. It will challenge you for a password. It is easy.
  • If the Toolkit Properties are not displayed and you get another error dialog box instead then there is a problem you need to report.
  • Update the External Cache to
    • On Windows (select one)
      • <installation-directory>\tomcat\Toolkits\ExternalCache
      • /C:/<installation-directory>/tomcat/Toolkits/ExternalCache
    • (On *nix)
      • <installation-directory>/tomcat/Toolkits/ExternalCache
  • Update Toolkit Port to 9770
  • Update Toolkit TLS Port to 9773
  • Note other port numbers with default values:
    • Proxy Port is 7297
    • PIF Listener Port Range is 5000-5020
  • Click Save
  • Refresh (Ctrl+F5) browser for settings to take effect.
  • XDS Toolkit should load without errors.
Stopping XDS Toolkit
     REM To shutdown Tomcat
     %CATALINA_HOME%\bin\shutdown.bat
Stopping XDS Toolkit
     # To shutdown Tomcat
     $CATALINA_HOME/bin/shutdown.sh
Troubleshooting

Check <installation-directory>/tomcat/Toolkits/XdsToolkit/logs for error messages. If there are any port conflicts, check to see if the required ports are free and available to be used by XDS Toolkit.

Optional: Configure XDS Toolkit Keystore (TLS)

  • The TLS ports from the toolkit.properties should be updated to match Tomcat configuration <installation-directory>/tomcat/Toolkits/XdsToolkit/conf/server.xml.
  • The Toolkit environment certificate must use the same copy as <installation-directory>/tomcat/Toolkits/XdsToolkit/connectathon-certificate/keystore.
  • You may copy the provided XdsToolkit/connectathon-certificate/keystore to ExternalCache/environment/default/keystore file. This is used for all outbound-TLS connections in the Default Toolkit environment.
  • The keystore makes use of the European Gazelle Security Suite (GSS) CA issued certificate (Id 3129). Certificate details can be viewed from: https://gazelle.ihe.net/gss/certificate/view.seam?id=3129
Clone this wiki locally