Source Code Install (Windows)

Prior to installing the CONNECT Gateway from source, it is recommended to review the CONNECT Software Architecture, Source Code Information, Release Notes, and Component Versions.

Having install issues? Visit the forums!

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.

Contents

Request Object Identifier

Each gateway has a unique identifier known as the OID (Object Identifier) or Home Community ID. The instructions located in the link below can be used to request an OID.

Request Object Identifier

Use the following table to determine if your system requires an object Identifier:

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 NHIN-CONNECT gateway software requires the following minimum hardware specifications:

Software Requirements

This section describes any dependent software products.

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 to 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: that 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.

Command Line
To perform a checkout via command line, perform the following command:

svn checkout https://svn1.connectopensource.org/svn/Nhin_Public/releases/3.0
 C:\Projects\NHINC\3.0

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.0 in the URL of Repository field.

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

Follow the JDK installation instructions located here.

Install NetBeans 6.7.1 bundle with GlassFish2.1.1 Application Server

Download the NetBeans 6.7.1 installer from NetBeans.org, selecting the "Java" bundle of the IDE. At the time of writing this document, the direct link to the Netbeans was [Windows|Linux].

Follow the installation instructions provided on the download page.
NOTE: the bundle includes two versions of GlassFish, a 2.1.1 version and a preview of the 3.0 version. CONNECT uses the 2.1.1 version only, so it is recommended to not install the 3.0.

NOTE: The CONNECT development customizes the default AppServer install directory to C:\Sun\AppServer and NetBeans to C:\Program Files\NetBeans 6.7.1

Set Environment Variables

CONNECT takes advantage of environment variables for some configuration setting. 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 your local path used when pulling source code.

JAVA_HOME=C:\Java\jdk1.6.0_16
ANT_OPTS=-Xmx872m -XX:MaxPermSize=640m "-Dcom.sun.aas.instanceName=server"
ANT_HOME=%NHINC_SOURCE_DIR%\Build\Packages\Ant\Ant
IDE_HOME=C:\Program Files\NetBeans 6.7.1
AS_HOME=C:\Sun\AppServer
NHINC_SOURCE_DIR=C:\Projects\NHINC\3.0
NHINC_PROPERTIES_DIR=C:\Sun\AppServer\domains\domain1\config\nhin
PATH - Append %JAVA_HOME%\bin;%ANT_HOME%\bin

Install Metro 1.5

Metro is a component that is included with GlassFish. However, a newer version is required for CONNECT. This installation will overwrite several Metro related files that reside in the GlassFish library directory.

Download Metro 1.5 Installer from Metro Download Site.

Open a command prompt, navigate to the directory with the downloaded Metro jar file (metro-1_5.jar). Enter the following command:

java -jar metro-1_5.jar

Read the License Agreement and click the Accept button. This will unpackage the jar file and create a metro subdirectory.

Enter the following command:

cd metro
ant -f metro-on-glassfish.xml install

To confirm that this is successful, navigate to %AS_HOME%\lib and confirm that several files, including "webservices-rt.jar" have updated timestamps.

Common GlassFish Libraries

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

Several libraries must be installed as common GlassFish libraries.
Copy the following to the GlassFish 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
• Xerces files from %NHINC_THIRDPARTY_DIR%\Xerces
• NhincSAMLCallbackLib.jar, NhincCommonTypesLib.jar, NhincCommonDAO.jar, and NhincCommonLib.jar (from the latest build, these now get automatically copied when you build them).

You can do this by running the following commands at a command prompt:

set NHINC_THIRDPARTY_DIR=%NHINC_SOURCE_DIR%\ThirdParty
copy /Y "%NHINC_THIRDPARTY_DIR%\C3PO\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\log4j\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\HibernateLibraries\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\MySQLDB\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\XStream\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\SpringFramework\*.jar" %AS_HOME%\lib\
copy /Y "%NHINC_THIRDPARTY_DIR%\Xerces\*.jar" %AS_HOME%\lib\

CONNECT Configuration files

This step moves CONNECT configuration files to the location that is used at run-time

Create a nhin directory in \AppServer\domains\domain1\config\

Copy contents in \Product\Production\Common\Properties\Dev\ to \AppServer\domains\domain1\config\nhin\

Copy \Product\Production\Common\Properties\Dev\log4j.properties to \AppServer\domains\domain1\config\

You can do this by running the following commands at a command prompt:

mkdir %AS_HOME%\domains\domain1\config\nhin
xcopy /S /Y "%NHINC_SOURCE_DIR%\Product\Production\Common\Properties\Dev\*.*"
 %AS_HOME%\domains\domain1\config\nhin
copy /Y "%NHINC_SOURCE_DIR%\Product\Production\Common\Properties\Dev\log4j.properties"
 %AS_HOME%\domains\domain1\config

Setup GlassFish Application Server Certificate

With the implementation of the UDDI Registry Service in CONNECT R2.4, Entrust certs are required to communicate with the UDDI registry and cross-gateway. In a stand alone or development environment, the 2 way SSL certificates are used as in the previous releases of CONNECT.

The following instructions apply for use in the stand alone or development environment. The installation instructions for Entrust certs can be found here: Entrust Certificates

Certificate Request and Installation

Instructions to download and install the certificates are found here: http://java.sun.com/webservices/refe....html#wp138685. These instructions are summarized below for convenience.

Download copyv3.zip.

Unzip copyv3.zip file, creating a "copyv3" directory. Navigate to the newly created "copyv3" directory and issue the following commands:

cd copyv3
ant

The command window will echo back the certificates that are being added to the keystore and truststore files, and should look something like this:

[echo]WARNING: currently we add non-CA certs to GF truststore, this will not be required in later
releases when we WSIT starts supporting CertStore(s)
[java] Added Key Entry :xws-security-server
[java] Added Key Entry :xws-security-client
[java] Added Trusted Entry :xwss-certificate-authority
[java] Added Key Entry :wssip
[java] Added Trusted Entry :xws-security-client
[java] Added Trusted Entry :xws-security-server
[java] Added Trusted Entry :wssip
[echo] Adding JVM Option for https outbound alias, this will take at least One Minute.
...

NOTE: Be patient as this may take a few minutes. To verify that the updates were successful, follow these steps:

cd %AS_HOME%\domains\domain1\config
keytool -list -keystore cacerts.jks -alias wssip -storepass changeit

If the wssip certificates are successfully updated, your response will look something like this:

wssip, Dec 15, 2009, trustedCertEntry,
Certificate fingerprint (MD5): 1A:0E:E9:69:7D: D0:80:AD:5C:85:47:91:EB:0D:11:B1

If the certificate update failed, your response will look something like this:

keytool error: java.lang.Exception: Alias <wssip> does not exist

For the next validation step, issue the following:

cd %AS_HOME%\domains\domain1\config
keytool -list -keystore keystore.jks -alias xws-security-server -storepass changeit

If the xws-security-server certificates were successfully updated, your response should look something like this:

xws-security-server, Dec 15, 2009, PrivateKeyEntry,
Certificate fingerprint (MD5): E4:E3:A9:02:3C:B0:36:0C:C1:48:6E:0E:3E:5C:5E:84

If the update failed, your response will look more like this:

keytool error: java.lang.Exception: Alias <xws-security-server> does not exist

Self-Signed Certificates

If you want to use self-signed certificates, you can find the instructions for creating and installing them here: self-signed Certificates
Please note that these are general instructions and you may want to use different values for some of the input values, like alias, host name, etc. For example, the value "internal" is used as the alias name in the instructions and you may want to use a different alias name when creating your self-signed certificates.

GlassFish configuration

The following steps customize the GlassFish configuration. This document explains how to do this by modifying the domain.xml file, but this could be done by accessing the GlassFish web admin console as well.  If modifying the domain.xml file directly, first confirm that Glassfish is stopped.

The installed domain.xml has changed from the previous version - DO NOT COPY OVER WITH PREVIOUS VERSION

Make a backup copy of the %AS_HOME%\domains\domain1\config\domain.xml file.

Memory Options

Set memory options by adding/modifying the following JVM options to domain.xml (%AS_HOME%\domains\domain1\config\domain.xml) (Note that some of these settings may already exist. If so, verify that they are set to the correct values.):

        <jvm-options>-XX:MaxPermSize=132m</jvm-options>
        <jvm-options>-Xmx1400m</jvm-options>
        <jvm-options>-XX:PermSize=132m</jvm-options>
        <jvm-options>-Dsun.rmi.dgc.server.gcInterval=1200000</jvm-options>
        <jvm-options>-Dsun.rmi.dgc.client.gcInterval=1200000</jvm-options>

These memory settings were testing on a Windows machine running with 4GB of memory.

Configure Certificates

Enable mutual authentication of certificates in the domain.xml file, by setting the client-auth-enabled attribute of the ssl element in the secure (port 8181) http-listener to true.  This would appear as follows:

NOTE: The below cert-nickname="wssip" is correct if you're using the copyv3 certs in the Install Glassfish Certificates section of this document. 

        <http-listener acceptor-threads="1" address="0.0.0.0" blocking-enabled="false"
         default-virtual-server="server" enabled="true" family="inet" id="http-listener-2"
         port="8181" security-enabled="true" server-name="" xpowered-by="true">
            <ssl cert-nickname="wssip" client-auth-enabled="true" ssl2-enabled="false"
             ssl3-enabled="true" tls-enabled="true" tls-rollback-enabled="true"/>
        </http-listener>

Configure the JVM for these certificates by adding/modifying the following JVM options to domain.xml (%AS_HOME%\domains\domain1\config\domain.xml) (Note that some of these settings may already exist. If so, verify that they are set to the correct values.):

NOTE: When using Entrust certs, the following configuration is not required as it has already been accomplished in that process. 

<jvm-options>-Dcom.sun.jbi.httpbc.enableClientAuth=true</jvm-options>
<jvm-options>-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks</jvm-options>
<jvm-options>-Djavax.net.ssl.keyStorePassword=changeit</jvm-options>
<jvm-options>-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks</jvm-options>
<jvm-options>-Djavax.net.ssl.trustStorePassword=changeit</jvm-options>
<jvm-options>-DSERVER_KEY_ALIAS=xws-security-server</jvm-options>
<jvm-options>-DCLIENT_KEY_ALIAS=xws-security-client</jvm-options>

Resolution of WSDL path

In previous releases of CONNECT, the wsdls had to be included with the release and placed in the same directory path as used during the build. This has been resolve in this release. The resolution includes settinga separate jvm-option in the domain.xml. Add the following to resolve the hardcoded WSDL path issue.

<jvm-options>-Dwsdl.path=file:${com.sun.aas.instanceRoot}/config/nhin/wsdl/</jvm-options>

Enable Logging

If desired, enable logging for SAML Request/Response Messages by adding/modifying the following JVM options to domain.xml (%AS_HOME%\domains\domain1\config\domain.xml):

<jvm-options>-Dcom.sun.xml.ws.transport.http.HttpAdapter.dump=true</jvm-options>
<jvm-options>-Dcom.sun.xml.ws.transport.http.client.HttpTransportPipe.dump=true </jvm-options>
<jvm-options>-Djavax.enterprise.resource.xml.webservices.security.level=FINE</jvm-options>
<jvm-options>-Djavax.enterprise.resource.webservices.jaxws=FINE</jvm-options>

log4j Configuration

Configure GlassFish to utilize the log4j configuration file for custom application logging by adding/modifying the following JVM options to domain.xml (%AS_HOME%\domains\domain1\config\domain.xml):

<jvm-options>-Dlog4j.configuration=file:${com.sun.aas.instanceRoot}/config/log4j.properties
 </jvm-options>

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

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:

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:

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 NHIN 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

Run NetBeans and Start GlassFish

Launch NetBeans. Navigate to the Services tab and open the Servers folder.
Right-click on GlassFish and click Start.

When GlassFish has successfully started, the "GlassFish v2.1" output tab will display the words, "Application server startup complete."

If you do not see the GlassFish server listed, there is likely an issue with the domain.xml file. If you copy-and-pasted from the wiki, there may have been an issue with handling of special characters. Check each line and make sure each line is correct. Also, check any comments that you may have added to ensure that they are properly formatted XML (i.e. start/end with the correct XML comment sequence). Sometimes one of the '-' or '\' characters is dropped.

Stop Glassfish: Right-click on GlassFish and click Stop.

Build CONNECT

The step will build the CONNECT source code

From a command prompt, issue the following commands:

cd %NHINC_SOURCE_DIR%\Product
ant clean package.create

The build may take about an hour to build the first time, depending on machine speed.

Platform Independent Deployment

The step will deploy CONNECT to GlassFish. If the Glassfish server is not already running, make sure it is started before deployment. You may choose to do this through other means, including through the GlassFish admin console.  

From a command prompt, issue the following commands:

cd %NHINC_SOURCE_DIR%\Product
ant deploy

Validation Tests for System Verification

This completes the installation and configuration of the NHIN CONNECT Gateway System. The next step for the installer is to verify the installation by running the Soap UI Self Tests to ensure the installation was successful.

See this page for running validation tests.