DRAFT

CONNECT Installation Windows JBoss

Version 0.1

CONNECT Release 3.2

24 June 2011

CONNECT Installation Windows JBoss Page-i

Version 0.1 - 06/24/2011

REVISION HISTORY

REVISION DATE DESCRIPTION

0.1 24 June 2011 First Draft Release

CONNECT Installation Windows JBoss Page-ii

Version 0.1 - 06/24/2011

TABLE OF CONTENTS

SOURCE CODE INSTALL (WINDOWS – JBOSS) ............................................................................................... 3

REQUEST OBJECT IDENTIFIER .................................................................................................................................... 3 TEST DEPLOYMENT FOOTPRINT ................................................................................................................................. 3

Hardware Requirements ....................................................................................................................................... 3 Software Requirements ......................................................................................................................................... 3 Federal Gateway Interface (WSDL) Ports ............................................................................................................ 4

INSTALL SUBVERSION CLIENT ................................................................................................................................... 4 DOWNLOAD SOURCE CODE FROM SOURCE CODE REPOSITORY .................................................................................. 4 INSTALL JAVA PLATFORM STANDARD EDITION (JAVA SE) 6 UPDATE 18 .................................................................. 5 SET ENVIRONMENT VARIABLES ................................................................................................................................. 5 SETUP SERVER CERTIFICATE FOR JBOSS .................................................................................................................... 6 INSTALL AND PREPARE JBOSS FOR CONNECT ......................................................................................................... 6

Install JBOSS ........................................................................................................................................................ 6 Configure certificates and Enable Security on JBOSS ......................................................................................... 6 Install Metro 1.5 on JBOSS .................................................................................................................................. 8 Adjust Memory Settings ........................................................................................................................................ 8 Adjust the Maximum Thread Count ...................................................................................................................... 9 Add Third Party Libraries to JBoss ...................................................................................................................... 9

BUILD CONNECT ................................................................................................................................................... 10 DEPLOY CONNECT TO JBOSS ............................................................................................................................... 10

Deploy CONNECT Libraries .............................................................................................................................. 10 Deploy CONNECT Configuration files ............................................................................................................... 10 Deploy CONNECT .war files .............................................................................................................................. 10

DATABASE SETUP ..................................................................................................................................................... 11 Install MySQL ..................................................................................................................................................... 11 Install MySQL Admin Tool ................................................................................................................................. 12 Create Nationwide Health Information Network Database Schemas and Tables .............................................. 12

VALIDATION TESTS FOR SYSTEM VERIFICATION ..................................................................................................... 13 CONFIGURATION OF PROPERTY FILES: ...................................................................................................................... 13

CONNECT Installation Windows JBoss Page-3

Version 0.1 - 06/24/2011

Source Code Install (Windows – JBOSS)

These instructions are intended to be used by a developer to set up this version of CONNECT by pulling

source code from the source code repository, and then compiling and deploying.

Request Object Identifier [TBD]

Test Deployment Footprint

Hardware Requirements

This section describes the recommended minimum hardware component infrastructure including

processor performance, disk space, and RAM for the application server platform. This is

provisional information subject to change based on continued development.

The Nationwide Health Information Network-CONNECT gateway software requires the

following minimum hardware specifications:

Item Version

Processor Minimum dual 2GHz CPU

RAM Minimum of 6 GB

Hard Disk Size Application Dependent on the deployment configuration.

For sizing purposes, assume 100K per CCD record,

1K per audit log record. (The testing environment allocated 20GB.)

Hard Disk Speed Minimum of 7200 RPM and 10000 RPM preferred.

Network Interface 100MB Ethernet acceptable; 1GB Ethernet desirable

Software Requirements

This section describes any dependent software products.

Item Description Platform

Operating System Windows 7 (64 bit platform) Server

Java-JRE/JDK Java SDK 1.6 Update 18 (64-bit version) Server

CONNECT Installation Windows JBoss Page-4

Version 0.1 - 06/24/2011

Application Server JBOSS AS 5.1.0.GA Server

Communication Stack jbossws-metro-3.2.2.GA

Metro 1.5

Server

Network Protocol TCP/IP Server/Client

Relational Database Any ANSI SQL92 compliant relational

database.

For example, MySQL 5.1, Oracle, and DB2

Server

Recommended Dev

Environment (Optional)

Netbeans 6.7.1 build 20090407 Server/Client

Recommended Test

Tools (Optional)

soapUI v3.5.1, JUnit Server

Ant Ant 1.7.1 (No need to download separately, it

comes with CONNECT source code)

Server

Federal Gateway Interface (WSDL) Ports

Click here to view the public WSDL Interfaces currently supported by the Federal Gateway.

Install Subversion Client To pull code, you will need a subversion client. If you need assistance, look here.

Download source code from Source Code Repository

CONNECT allows for anonymous checkout of source code for the Source Code Repository

(Subversion). This step instructs how to pull the code locally using either command line or

Tortoise (GUI). The examples will show a local structure of "C:/Projects/NHINC/3.x/". This is

the "recommended" path, but it is okay to pull from the local directory of your choice. This local

path will be referred to by the environment variable "NHINC_SOURCE_DIR" later in this

document.

NOTE: You may be prompted about an invalid certificate while pulling the source code. The

current certificate is self-signed and thus not valid. This is a known issue being worked. You

may choose to ignore the warning and accept the certificate.

NOTE: the first checkout may take a long time to pull everything locally.

CONNECT Installation Windows JBoss Page-5

Version 0.1 - 06/24/2011

Command Line

Use the following command to perform a checkout via the command line:

svn checkout https://svn1.connectopensource.org/svn/Nhin_Public/releases/3.2

C:\Projects\NHINC\3.2

TortoiseSVN

To perform a checkout via TortoiseSVN, first create a local folder. Right click on the folder,

select SVN Checkout, and enter

https://svn1.connectopensource.org/svn/Nhin_Public/releases/3.2 in the URL of Repository field.

Install Java Platform Standard Edition (Java SE) 6 Update 18

Follow the JDK installation instructions located here.

Set Environment Variables

CONNECT takes advantage of environment variables for some configuration settings. For

instructions on how to set environment variables, look here.

NOTE: Paths may need to be adjusted if default locations were not used. A common mistake is

not setting the JAVA_HOME correctly. On some installations, this is put into "c:\program

files\java", others have had it at "c:\java\". Also, change the value for NHINC_SOURCE_DIR

based on the local path used to pull the source code.

JAVA_HOME=C:\Java\jdk1.6.0_18

ANT_OPTS=-Xmx872m -XX:MaxPermSize=640m

ANT_HOME=%NHINC_SOURCE_DIR%\Build\Packages\Ant\Ant

IDE_HOME=C:\Program Files\NetBeans 6.7.1 (Optional)

JBOSS_HOME= C:\jboss-5.1.0.GA

NHINC_SOURCE_DIR=C:\Projects\NHINC\3.2

NHINC_PROPERTIES_DIR=%JBOSS_HOME%\server\default\config\nhin

PATH - Append %JAVA_HOME%\bin;%ANT_HOME%\bin

CONNECT Installation Windows JBoss Page-6

Version 0.1 - 06/24/2011

Setup Server Certificate for JBoss [TBD]

Install and prepare JBoss for CONNECT This is a multi-step process as detailed in the following sub sections: Installing JBoss, enabling

security, installing Metro, adjusting memory settings and adding 3rd

party libraries.

Install JBOSS

Download and unzip jboss-5.1.0.GA-jdk6.zip into a directory where you want to install

JBoss. For example if it’s unzipped under C:\, the path would look like C:\jboss-5.1.0.GA

which is the JBoss home directory.

Add the environment variable: JBOSS_HOME to point to the JBoss home directrory.

To verify JBoss is installed properly, open a command prompt window, go to

%JBOSS_HOME%\bin and execute “run.bat –b 0.0.0.0” to start the JBOSS server.

Note: Without “-b 0.0.0.0” option, webserver is not available from outside the hosting

machine. Verify that there are no exceptions thrown on the console and JBoss is listening

on port 8080. Please note that SSL port may not have been enabled yet at this point.

Open browser and check the server is up by checking the connection via the urls:

http://localhost:8080 and http://<your_machine_name>:8080

Shutdown the server by hitting Ctrl+C from the same commandline. Note: you can use

the shutdown command “shutdown.sh –S” from other command prompts.

Configure certificates and Enable Security on JBOSS

Copy cacerts.jks and gateway.jks to %JBOSS_HOME%\server\default\conf.

Open server.xml under %JBOSS_HOME%\server\default\deploy\jbossweb.sar in a text

editor, uncomment the section shown below and update with the keystore details as

shown below. <!-- SSL/TLS Connector configuration using the admin devl guide

keystore-->

<Connector protocol="HTTP/1.1" SSLEnabled="true"

port="8443" address="${jboss.bind.address}"

scheme="https" secure="true" clientAuth="false"

keystoreFile="${jboss.server.home.dir}/conf/gateway.jks"

keystorePass="<keystore password>" sslProtocol = "TLS" />

Open properties-service.xml under %JBOSS_HOME%\server\default\deploy in a text

editor and change the SystemPropertiesService MBean configuration with the security

information as shown below:

CONNECT Installation Windows JBoss Page-7

Version 0.1 - 06/24/2011

<mbean code="org.jboss.varia.property.SystemPropertiesService"

name="jboss:type=Service,name=SystemProperties">

<attribute name="Properties">

javax.net.ssl.keyStore=${jboss.server.home.dir}/conf/gateway.jks

javax.net.ssl.keyStorePassword=<keystore password>

javax.net.ssl.keyStoreType=JKS

javax.net.ssl.trustStore=${jboss.server.home.dir}/conf/cacerts.jks

javax.net.ssl.trustStorePassword=<truststore password>

javax.net.ssl.trustStoreType=JKS

SERVER_KEY_ALIAS=<server_key_alias>

CLIENT_KEY_ALIAS=<client_key_alias>

</attribute>

</mbean>

Issue: When the JBoss is started, the “jboss.server.home.dir” variable in the above settings is replaced with the absolute path but without path-separator and therefore fails at validating the security properties. Until this is figured out, please manually specify the hard-coded path of the server home with forward-slash as the path-sperator. For example: C:\jboss-5.1.0.GA\server\default\conf\gateway.jks and C:\jboss-5.1.0.GA\server\default\conf\cacerts.jks

Restart the JBOSS server and verify that the web site is accessible via SSL by connecting

to https://<machine name>:8443/admin-console in a browser.

CONNECT Installation Windows JBoss Page-8

Version 0.1 - 06/24/2011

Install Metro 1.5 on JBOSS

Installing metro on JBOSS is a two-step process. First we need to install JBoss-metro stack and then

upgrading it to Metro 1.5 by removing and replacing couple of jars with Metro 1.5 jars.

Install JBossWS-metro: This will install the JBOSS WS metro distribution o Download and unzip jbossws-metro-3.2.2.GA.zip into any folder. It will be unzipped with

the root folder name as jbossws-metro-bin-dist. o Go to jbossws-metro-bin-dist and look for the file ant.properties.example. Make a copy

of it with name ant.properties under same folder. o Edit ant.properties and change the variable “jboss510.home” to point to the JBoss home

directory (Example: jboss510.home=C:\jboss-5.1.0.GA). o From commandline, go to jbossws-metro-bin-dist and run the ant target: ant deploy-

jboss510. This will create a deployable structure under jbossws-metro-bin-dist/output/deploy-jboss510 and deploys it to JBoss. Verify this structure is deployed to JBOSS by checking the timestamps on the corresponding files and folders.

Install Metro 1.5: This will install Metro 1.5 in Jboss by replacing some of the JBoss WS metro distribution files with Metro 1.5.

o Remove the jar file jbossws-metro-wsit-rt.jar from %JBOSS_HOME%\server\default\deployers\jbossws.deployer

o Remove the jar file xws-security.jar from

%JBOSS_HOME%\server\default\deployers\jbossws.deployer

o Download Metro 1.5 o From the command line, go to the metro downloaded location and execute the

command “java –jar metro1_5.jar”. Read the License Agreement and Accept it. This will un-package the jar file and create a metro subdirectory.

o From command prompt, execute the following commands

copy metro\lib\webservices-rt.jar %JBOSS_HOME%\server\default\deployers\jbossws.deployer

copy metro\lib\webservices-api.jar %JBOSS_HOME%\lib\endorsed

Restart JBoss server and verify no exceptions are thrown.

Adjust Memory Settings

Update JAVA_OPTS in %JBOSS_HOME%\bin\run.conf.bat as shown below.

set "JAVA_OPTS=-Xms256m -Xmx4096m -XX:PermSize=512m -XX:MaxPermSize=2048m -XX:-UseGCOverheadLimit -Dorg.jboss.resolver.warning=true -Dnhinc.properties.dir=C:/jboss-5.1.0.GA/server/default/config/nhin -Dwsdl.path=file:/C:/jboss-5.1.0.GA/server/default/config/nhin/wsdl -Dcom.sun.jbi.httpbc.enableClientAuth=true -Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=false -Dsun.security.ssl.allowUnsafeRenegotiation=true -Dsun.security.ssl.allowLegacyHelloMessages=true"

CONNECT Installation Windows JBoss Page-9

Version 0.1 - 06/24/2011

Adjust the Maximum Thread Count

Update the attribute “MaximumPoolSize” in %JBOSS_HOME%\server\default\conf\jboss-service.xml to

set the value to 100.

Add Third Party Libraries to JBoss

This step will add third party libraries utilized by CONNECT to the JBoss library.

Several libraries must be installed as common JBoss libraries.

Copy the following to the JBoss library directory:

C3PO jar files from %NHINC_THIRDPARTY_DIR%\C3PO

Log4j jar files from %NHINC_THIRDPARTY_DIR%\log4j

Hibernate jar files from %NHINC_THIRDPARTY_DIR%\HibernateLibraries

MySQL jar from %NHINC_THIRDPARTY_DIR%\MySQLDB

XStream files from %NHINC_THIRDPARTY_DIR%\XStream

Spring Framework files from %NHINC_THIRDPARTY_DIR%\SpringFramework

Xerces files from %NHINC_THIRDPARTY_DIR%\Xerces

OpenSSO files from %NHINC_THIRDPARTY_DIR%\OpenSSO

You can do this by running the following commands at a command prompt. Verify the console

output to make sure the commands executed successfully without permission problems. set NHINC_THIRDPARTY_DIR=%NHINC_SOURCE_DIR%\ThirdParty

copy /Y %NHINC_THIRDPARTY_DIR%\C3PO\*.jar %JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\log4j\*.jar %JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\HibernateLibraries\*.jar

%JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\MySQLDB\*.jar %JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\XStream\*.jar %JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\XStream\*.txt %JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\SpringFramework\*.jar

%JBOSS_HOME%\server\default\lib\

copy /Y %NHINC_THIRDPARTY_DIR%\Xerces\*.jar %JBOSS_HOME%\server\default\lib\

move /Y %JBOSS_HOME%\server\default\lib\serializer.jar %JBOSS_HOME%\lib\endorsed

copy /Y %NHINC_THIRDPARTY_DIR%\OpenSSO\openssoclientsdk.jar %JBOSS_HOME%\server\default\lib

CONNECT Installation Windows JBoss Page-10

Version 0.1 - 06/24/2011

Build CONNECT This step will build the CONNECT source code. From a command prompt, issue the following commands: cd %NHINC_SOURCE_DIR%\Product

ant clean package.create

ant copy.deployable.artifacts

The ant taget “copy.deployable.artifacts” above will create and copy the deployable artifacts to a staging folder C:\NHINC which gets created by the ant target if doesn’t exist already.

Deploy CONNECT to JBOSS The CONNECT deployable artifacts consist of core libraries, configuration files and web applications.

Deploy CONNECT Libraries

Execute the following commands from the command prompt:

copy /Y C:\NHINC\nhinc\CONNECTCoreLib.jar %JBOSS_HOME%\server\default\lib copy /Y C:\NHINC\nhinc\CONNECTCommonTypesLib.jar %JBOSS_HOME%\server\default\lib

Deploy CONNECT Configuration files

Execute the following commands from the command prompt:

rmdir /S %JBOSS_HOME%\server\default\config mkdir %JBOSS_HOME%\server\default\config mkdir %JBOSS_HOME%\server\default\config\nhin xcopy /S /Y C:\NHINC\Dev\* %NHINC_PROPERTIES_DIR% copy /Y C:\NHINC\Dev\log4j.properties %JBOSS_HOME%\server\default\config xcopy /S /I /Y C:\NHINC\Interfaces\schemas %NHINC_PROPERTIES_DIR%\schemas xcopy /S /I /Y C:\NHINC\Interfaces\wsdl %NHINC_PROPERTIES_DIR%\wsdl

Deploy CONNECT .war files

copy /Y C:\NHINC\nhinc\CONNECTAdapterWeb.war %JBOSS_HOME%\server\default\deploy copy /Y C:\NHINC\nhinc\CONNECTCommonWeb.war %JBOSS_HOME%\server\default\deploy copy /Y C:\NHINC\nhinc\CONNECTGatewayWeb.war %JBOSS_HOME%\server\default\deploy copy /Y C:\NHINC\nhinc\CONNECTMsgProxyWeb.war %JBOSS_HOME%\server\default\deploy copy /Y C:\NHINC\nhinc\CONNECTNhinServicesWeb.war %JBOSS_HOME%\server\default\deploy

CONNECT Installation Windows JBoss Page-11

Version 0.1 - 06/24/2011

The Root contexts for the above .war files are listed below.

File Name Context Root Application Type

CONNECTAdapterWeb CONNECTAdapter Web

CONNECTCommonWeb CONNECTCommon Web

CONNECTGatewayWeb CONNECTGateway Web

CONNECTMsgProxyWeb CONNECTMsgProxyWeb Web

CONNECTNhinServicesWeb CONNECTNhinServicesWeb Web

NOTE: The .war files for the sample GUI applications may also be deployed. They are not included here

to help reduce the memory usage of the CONNECT deployment.

Database setup The Gateway and the reference implementation of the Adapter both use MySQL as the database.

The programmatic access to this database is done using Hibernate. When doing the initial

installation of the Gateway and Adapter, it is recommended that MySQL be installed and that the

system is verified. After the system has been verified, other relational databases can be used in

place of MySQL by altering the appropriate entries in the Hibernate configuration files for those

projects which are accessing the database. Directions for configuring Hibernate to use other

databases is not defined in this document.

Install MySQL

If a previous version of MySQL is installed, first backup the data and uninstall the previous

version before proceeding with the new install.

C:\Program Files\MySQL\MySQL Server 5.0\bin>mysqldump \-uroot \-pNHIE-Gateway

\--all-databases > c:\temp\nhincdb.sql

Uninstall of Previous 5.0 version

1. Open Control Panel > Add or Remove Programs

2. Look for MySQL Server 5.0 software and click on Remove button.

It is not necessary to uninstall MySQL Tools for 5.0. The same tools can be used for MySQL

5.1.

Download MySQL 5.1.41 and run the installation program (mysql-5.1.41-win32.msi).

Accept the default values during the install process until you reach the MySQL Server Instance

configuration screen. Choose Standard Configuration and enter the following:

CONNECT Installation Windows JBoss Page-12

Version 0.1 - 06/24/2011

Make sure the option to install MySQL as a windows service is selected.

Make sure the option to "include bin directory in windows path" is selected.

Root password: NHIE-Gateway

Install MySQL Admin Tool

If you have a previous install of MySQL tools, this section can be skipped.

Download MySQL GUI 5.0-r17 Tools and run the installation program (mysql-gui-tools-5.0-r17-

win32.msi).

Run the MySQL Administrator (Start->All Programs->MySQL->MySQL Administrator). Click

on the small dialog box containing three periods next to the "Stored Connections" field. If the

"Connections" panel is not showing, click on the "Connections" icon on the left-hand side of the

window. Click "New Connection" button.

On the Connections panel, enter the following values in the specified fields:

Connection: NHINConnect

Username: root

Password: NHIE-Gateway

Hostname: localhost

Port: 3306

Schema: test

Once the fields are entered, click the "Apply" button, then click the "Close" button.

Select your new database under the "Stored Connections" drop down menu.

Enter the user name as root and the password as NHIE-Gateway and select OK.

After the connection is verified, close the MySQL Administrator tool.

Create Nationwide Health Information Network Database Schemas and Tables

Open command prompt and issue the following command (Note that since the MySQL install

has made changes to the path environment variable, it will be necessary to open a new command

window.):

cd %NHINC_SOURCE_DIR%\Product\DBScripts\nhincdb

mysql -uroot -pNHIE-Gateway < nhincdb.sql

CONNECT Installation Windows JBoss Page-13

Version 0.1 - 06/24/2011

Validation Tests for System Verification

This completes the installation and configuration of the Nationwide Health Information Network

CONNECT Gateway System. The next step for the installer is to verify the installation by

running the SoapUI Self Tests to ensure the installation was successful.

See this page for running validation tests.

Configuration of property files: In order to test the gateway-to-gateway communication between two CONNECT Gateway instances, the

following properties files need to be moved and/or updated per your gateway environment.

mpi.xml. This files needs to be under %JBOSS_HOME%\bin

%NHINC_PROPERTIES_DIR%\adapter.properties

%NHINC_PROPERTIES_DIR%\gateway.properties

%NHINC_PROPERTIES_DIR%\internalConnectionInfo.xml

%NHINC_PROPERTIES_DIR%\AdapterMpiProxyConfig.xml