Source Code Install (Linux)

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

This installation was executed on a Red Hat 5 Linux distribution. Please refer to your Linux distribution documentation for specific installation steps. The user will need to run sudo or be root to execute several commands.

Having install issues? Visit the forums!

These instructions are intended to be used by a developer with root access to set up CONNECT Release 3.0 by pulling source code from the source code repository, 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

Hardare 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.

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

svn checkout https://svn1.connectopensource.org/svn/Nhin_Public/releases/3.0 <localpath>

Where <localpath> is the local working path to which you want to check code out (i.e., /Projects/NHINC/current). For example:

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

This local path will be referred to by the environment variable "NHINC_SOURCE_DIR" later in this document.

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

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

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

If Java SE 6u16 is already installed, please proceed to the next section.  Download Java SE6, Update 16 Installer from the Sun download site.

Make sure to download the JDK 6u16. Follow the installation instructions provided on the download page.

You need to run as root:

./jdk-6u<version>-linux-i586.bin

For the installation of NetBeans IDE in the next step, set the environment variable for JAVA_HOME to this location

Install NetBeans 6.7.1 bundle with GlassFish 2.1 Application Server

If the NetBeans 6.7.1 bundle with GlassFish2.1 Application Server is already installed, please proceed to the next section.  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].

From a command prompt:

netbeans-6.7.1-ml-java-linux.sh --silent --record netbeanstate.xml

• Netbeans (version 6.7.1) is installed in location you have selected.  Default: /<home>/NetBeans-6.7.1

• GlassFish2.1 is installed in location you have selected. Default:  /<home>/SUNWappserver

The Glassfish prelude v3.0 should be removed using the customize feature from the installation.

Set Environment Variables

You can ensure that when a shell starts that the environment is set up correctly by placing a nhin-profile.sh file in the /etc/profile.d directory.

ANT_OPTS="-Xmx872m -XX:MaxPermSize=640m -Dcom.sun.aas.instanceName=server"
IDE_HOME=/<home>/netbeans-6.7.1
AS_HOME=//<home>/SUNWappserver
NHINC_SOURCE_DIR=/Projects/NHINC/3.0(or location of source code)
ANT_HOME=$NHINC_SOURCE_DIR/Build/Packages/Ant/Ant
NHINC_PROPERTIES_DIR=//<home>/SUNWappserver/domains/domain1/config/nhin
JAVA_HOME=/usr/java/jdk1.6.0_16
PATH=$PATH:$ANT_HOME/bin:$JAVA_HOME/bin:/sbin:$AS_HOME/bin
export ANT_OPTS ANT_HOME IDE_HOME AS_HOME NHINC_SOURCE_DIR NHINC_PROPERTIES_DIR JAVA_HOME PATH

Notes:
An extra '/' is required for AS_HOME and NHINC_PROPERTIES_DIR in some cases for this current release.
<home> is the download location for netbeans

Install Metro 1.5

Metro is a component 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 Metro jar file (metro-1_5.jar).

Enter the following command:

 java -jar metro-1_5.jar -console

Read the License Agreement and Accept it. 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

Several libraries must be installed as common GlassFish libraries.
Copy the following to /SUNWappserver/lib:

• 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 file 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:

cp $NHINC_THIRDPARTY_DIR/C3PO/*.jar $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/log4j/*.jar $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/HibernateLibraries/*.jar $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/MySQLDB/*.jar $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/XStream/*.jar $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/XStream/*.txt $AS_HOME/lib/
cp $NHINC_THIRDPARTY_DIR/SpringFramework/*.jar $AS_HOME/lib/
cp $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 /SUNWappserver/domains/domain1/config/
Copy contents in $NHINC_SOURCE_DIR/Product/Production/Common/Properties/Dev/ to /SUNWappserver/domains/domain1/config/nhin/
Copy $NHINC_SOURCE_DIR/Product/Production/Common/Properties/Dev/log4j.properties to /SUNWappserver/domains/domain1/config/

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

	mkdir $AS_HOME/domains/domain1/config/nhin
	cp -r $NHINC_SOURCE_DIR/Product/Production/Common/Properties/Dev/*
          $AS_HOME/domains/domain1/config/nhin
	cp $NHINC_SOURCE_DIR/Product/Production/Common/Properties/Dev/log4j.properties
          $AS_HOME/domains/domain1/config

Setup GlassFish Application Server Certificate

NOTE: An issue was encountered running on a Linux VM that Glassfish was not able to resolve the host name and would fail to start the app server. Adding the hostname to /etc/hosts resolved the issue.

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 start 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 also can be done by accessing the GlassFish web admin console.

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):

       <jvm-options>-XX:MaxPermSize=256m</jvm-options>
       <jvm-options>-Xmx1230m</jvm-options>
       <jvm-options>-XX:PermSize=256m</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.

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 resolved in this release. The resolution includes setting a 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>

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. NOTE: Changing the alias in the following settings to "gateway" is only required if the alias used when creating entrust or self-signed certs is gateway. If using the default certs, s1as needs to remain the alias and this step can be skipped.

        <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="gateway" client-auth-enabled="true" ssl2-enabled="false"
             ssl3-enabled="true" tls-enabled="true" tls-rollback-enabled="true"/>
        </http-listener>

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

Configure the certificates by adding/modifying the following JVM options to domain.xml (<AS_HOME>\domains\domain1\config\domain.xml):

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

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>

Log4JConfiguration

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/nhin/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 be 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

At a command prompt enter the following:

yum install mysql mysql-server
chkconfig --level 345 mysqld on
service mysqld start
mysqladmin -u root password 'NHIE-Gateway'
mysql -uroot -pNHIE-Gateway
DELETE FROM mysql.user WHERE user="";
exit

NOTE: When installing as root, yum installs MySQL to /usr/bin. Verify the location of MySQL and add the following environment variables and update the path.

 which mysql
# use the response from the which command to set the environment variable.
# Using /usr/bin as an example.
export MYSQL_HOME=/usr/bin/mysql
export PATH=$PATH:$MYSQL_HOME/bin

Create NHIN Database Schemas and Tables

Open command prompt and issue the following command:

cd $NHINC_SOURCE_DIR/Product/DBScripts/nhincdb
mysql -uroot -pNHIE-Gateway < nhincdb.sql

Run NetBeans and Start GlassFish

Start Glassfish:

asadmin start-domain domain1

Stop Glassfish:

asadmin stop-domain domain1

Build CONNECT

If updating a previous version of CONNECT, there are several files in $AS_HOME/lib that are now obsolete and need to be removed from the directory, or unexpected errors will occur. Please execute the following commands if installing over a previous version of CONNECT: cd $AS_HOME/lib rm Nhinc*lib.* rm NhincCommonDAO.* rm AssigningAuthoritiesToHomeCommunityMappingDAO.jar

.

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.

Also, there are several downloads on the initial configuration for ivy and maven support. It has been experienced that these downloads can hang/suspend. If this should happen for prolonged periods, interrupt the build and restart. This is known to have resolved the problem.

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.