web stats
Skip to end of metadata
Comment: Migrated to Confluence 4.0
Go to start of metadata

Installation Notes

Requirements

  • An instance of Glassfish v2.1.1 has been installed. Mirth Match requires that you have installed Glassfish 2.1.1.
  • A database, preferably PostgresSQL download. Mirth Match is currently tested with Postgres 8.3 and Oracle 11g.

Once you've completed these steps successfully, you can move on to the following steps. You may also want to install Netbeans 6.7.1 or greater if you will be extending or making code changes to Mirth Match.

Define environment variables

The locations specified below are the default. If you would like put these at a different location, you will need to replace the below paths with your specified location.

Linux / Mac OSX

Add the following variables to your .bashrc file.

The locations are the defaults, please replace them with the appropriate locations for your system.

  1. Add the following lines to ~/.bashrc for linux and likely ~.profile for the Mac

You will need to exit from your shell or console instance for these changes to take effect

Mac Note:  Clean this up later

Mac OSX is weird.  You need to edit a file ~/.MacOSX/environment.plist to get the OS to 'see' those vars, particularly from Glassfish. 

http://www.rubicode.com/Software/RCEnvironment/

http://garyboone.com/2009/06/understanding-mac-environment-variables/?wscr=1920x1200

Windows

Create the following suggested System level environment variables:

* The locations are the defaults, please replace them with the appropriate locations for your system.

Installing Mirth Match

As an early adopter, you should have access to Mirth Match releases on our SFTP server. Once you have connected, follow these steps:

  • Version 1.0 and later:
    • Download \files\mirthmatch\application\<release_number>\MirthMatch.zip and unzip in your c:\opt or /opt directory.
  • Prior to version 1.0:
    • Copy \files\mirthmatch\application\<release_number>\opt to your c: drive (or root directory). You should now see c:\opt\mirthmatch or /opt/mirthmatch. If you already have an c:\opt or /opt directory, then just copy \files\mirthmatch\application\<release_number>\opt\mirthmatch into that.
    • Copy \files\mirthmatch\application\<release_number>\MirthMatch\MirthMatch.ear to c:\opt\mirthmatch\ops.

The Ops Directory

The ops sub-directory will be the location that contains scripts for backing up and restoring Mirth Match's backing data base as well as scripts deploy Mirth Match to glassfish.

At this point, the following files should be in the $MIRTH_MATCH_HOME directory:

  • deploy.sh - this shell script will take a file named MirthMatch.ear located in the ops directory and deploy that file to the glassfish server running on localhost, utilizing the admin password stored within the file password.txt

    For a deploy to be successful, you must have already created the Java EE resources (JMS queues, JDBC connection pool, etc) that Mirth Match relies upon. You should also have created the default database for Mirth Match on the database server that is pointed to by the mirthmatch connection pool. This will typically be a PostgreSQL database named mirthmatch running on localhost.

  • MirthMatch.ear - the MirthMatch enterprise application
  • password.txt - the password to use for MirthMatch
  • undeploy.sh - this shell script will undeploy the MirthMatch enterprise application from the glassfish instance running on localhost

The Plugins Directory

The plugins sub-directory will be the location that contains the jars for any plugin components utilized by Mirth Match. At this point in Mirth Match, these jars will be either Matching Module plugins or Event Notification plugins. There may be more types or styles of plugins later, but regardless, this directory will be where they are placed.

Other sub-directories

There may be more sub-directories added under the MIRTH_MATCH_HOME directory at run-time automatically by the application. These directories will be used for such purposes as file uploads and downloads from Mirth Match, etc.

Review

The $MIRTH_MATCH_HOME directory should now look like the following file map

Glassfish Configuration

Add Glassfish environment variables

Add the following lines to asenv.(conf | bat) in the $AS_HOME/config directory. These values of these variables should match the values of the system environment variables.

This is the only way I know of to make this environment variable visible in the JVM. We can probably factor this out at some time.

Linux / Mac OSX

(file: $AS_HOME/config/asenv.conf)

Windows

(file: %AS_HOME%/config/asenv.bat)

Set the port for Glassfish

Editing the domain.xml file requires that glassfish be stopped; otherwise, the changes will be overwritten when it is stopped/restarted. You can stop Glassfish by issuing the following command: service glassfish stop

Go to your $AS_CFG/domain.xml and search for the "http-listener" xml element. There should be three of them, each with their own port value. The first one you'll notice is 8080. Change it to 8888.

Increase Glassfish JVM Memory Size

Also in $AS_CFG/domain.xml, make sure the following are set as minimum requirements:

If you are expecting to load millions of patients in your installation, you should have at least 3 GB for the heap:

Additional configuration for NHIN CONNECT users

If you are using NHIN CONNECT on the same host, it is important for you to remove the ehcache jars located in $AS_HOME/lib and copy all the jars located at the sftp server at /files/mirthmatch/application/libs/Ehcache to $AS_HOME/lib.

Create the Glassfish service for init.d

On a system that already has MirthResults installed, there is probably already a script called mirth-mirthresults that can be used to start and stop glassfish

For Windows installs, Glassfish can be started and stopped as a servicem, by hand using the asadmin command, or in a development mode by starting and stopping the service within your IDE via an appropriate Glassfish plugin.

  1. In order to allow Glassfish to be started and stopped as a service, create a startup script called glassfish located in the /etc/init.d directory with the contents of the code located below. 
    (file: /etc/init.d/glassfish)
  2. Make it executable.
  3. Once you have created that file, register this service with the operating system so that it will automatically start when the system is booted.
  4. Verify that this script is working by issuing the following commands individually.

Setup Kana Realm

If MirthResults has already been setup on this system, this step may have already been completed.

  1. Add the following lines to the login.conf file located in the AS_CFG directory. This entry defines a new type of security realm for glassfish called KanaRealm that is used by all Kana applications.
    (file: $AS_CFG/login.conf)
  2. Add the KanaRealm jar (located on the SFTP site under the kana directory) to $AS_HOME/domains/domain1/addons
  3. Add the required JARS to $AS_HOME/domains/domain1/lib/ext.
    • IBM Password Authentication
      1. ibmjcefips.jar
      2. ibmpkcs.jar
    • Database Driver (Pick the appropriate one)
      • Postgres: postgresql-<VERSION>.jdbc4.jar (download)
      • Oracle: ojdbc<VERSON>.jar

Create the necessary Glassfish resources

In order to complete the following step glassfish must be running. You can verify this by executing: service glassfish start

Mirth Match makes use of a JDBC connection pool, a couple JMS queues, a JMS Topic and a security Realm. The following commands create the resources, authentication realm, and set the classpath for Glassfish.

  1. Change directory to $MIRTH_MATCH_HOME/ops, as we will need to have access to the password.txt and mirthmatch_gf_resources.xml files
  2. Make sure glassfish is started
  3. Run the following commands:

Mirth Match Database Configuration

  1. Create an empty database named mirthmatch with user role mirthmatch on localhost in PostgreSQL.

You may need to end SQL Shell commands with "\g" instead of a ";" then press <Enter> to execute on a Windows installation.

You can also perform these steps graphically using a database admin client like pgadmin.

Since we've incorporated the DBManager into Mirth Match, we no longer need to maintain a 'master' database schema that is played to initialize the schema.  This is pretty neat, IOHO.  When the application EAR is deployed to glassfish, the application detects that the schema is empty and creates all the necessary database objects and then populates the default application meta-data.  Also, subsequent releases of the application that affect the schema for Mirth Match automatically detect the database version and apply only the required schema changes to the application.  *woot*

Smoke testing the installation – Did it work??

Testing your JDBC Connection pool

  1. Open the Glassfish administration page by pointing your browser at http://localhost:4848/ and logging in. The default login credentials for Glassfish are admin/adminadmin.
  2. On the sidebar on the right, locate the mirthmatch Connection Pool under the Resources->JDBC->Connection Pools, and select the connection pool for editing.
  3. On the main content pane, locate and click the Ping button.
  4. If your jdbc connection is correctly set up, you should receive a Ping Succeeded message. If you do not, then please take steps to address this issue until you can successfully Ping the Connection Pool.

Mirth Match Operation

In order to deploy and run Mirth Match, your Glassfish server must be running.

If you have been able successfully complete the above steps, your machine and Glassfish have been successfully configured for Mirth Match.

Deploying

There are several ways to deploy a GlassFish enterprise application (EAR file) to an application server.  You may use asadmin and manually deploy the application.  You can also deploy via the administration UI for Glassfish (http://yourappserverhost:4848)).  We also provide a simple batch script:

  1. To deploy Mirth Match, change directory to MIRTH_MATCH_HOME/ops
  2. Run the deploy script. (deploy.sh for Linux/Mac OSX; deploy.bat for Windows)

First Login

Once Mirth Match has been deployed, you should now be able to access the Mirth Match Admin Console. To do this:

  1. Open to a web browser, and navigate to http://localhost:8888/MirthMatch. This should bring up a log in page.
  2. Log in with user admin and password admin 
  3. Once here, go to the Administration page and change the password for admin if you are so inclined.