Last updated March 18, 2010 21:09, by odysseas
» Share this     Feedicon

Installation Instructions

The first step involves the installation of the database server. Currently OpenEMPI only support Postgres although porting to other databases should not be difficult. All access to the database is done through Hibernate and no Postgres specific features are being used by OpenEMPI. If there is an interest to have it support other databases, please raise an issue through Issue Tracking or better yet, implement the support and contribute it to the community.

Installation of the Postgres Database Server

The PostgreSQL site has detailed installation instructions for the database but we provide some basic installation instructions here to get you started. Refer to the PostgreSQL site or post a message in the Users forum if you run into problems.

The latest version of PostgreSQL that has been tested is 8.3.7. After you download the one-click distribution, run the executable, which will bring up the setup window shown below.

After pressing the next button, you are given the option of selecting the installation directory for Postgres. You can install it anywhere but for the rest of these instructions we will assume that you selected the default directory of d:\servers\postgres-8.3. Pressing the next button takes you to the next screen which allows you to select the directory under which to store data. The default directory is fine as a subdirectory of the root directory for Postgres.

The next page allows you to select a password for the database superuser posgres account. If the postgres service account already exists on your system because of a previous installation of postgres, you must use that existing account's password to continue. If the postgres service account does not exist prior to the installation of Postgres, the installer may complain about you entering an invalid password for the service account. You can get around this issue by first creating the Windows User account postgres, assigning it a password and then running the Postgres installation again.

The next page allows you to set the port on which postgres listens for requests on. Unless you already have another application using that port, you can use the default of 5432. The last and final wizard screen allows you to select the locale to be used by the database cluster. Pressing Next will take you to the final screen before installation actually begins.

This completes the installation of the database server software.

Application Server Installation Instructions

OpenEMPI has been tested primarily on the JBoss Application Server although it is deployed as a J2EE application that can be hosted on any J2EE-compliant application server. OpenEMPI 2.0 now supports two deployment scenarios:

  • You can deploy it as a web-based application (deploy the war file) and access its functionality through the new web-based console. The war file can be deployed on any container that supports the deployment of WAR files and has been tested on tomcat 5.5, 6.0, jetty and JBoss 2.4.3.
  • You can it as a J2EE application which utilizes the EJB 3.0 specification to expose its functionality using a few stateless session beans. In this case you want to deploy the .ear file from the distribution and presumably it should work on an J2EE server that supports EJB 3.0 or above but in practice your mileage may vary. We have tested its deployment against the JBoss Application Server.

If you need support on another J2EE application server you may raise an issue in the Issue Tracking or do the port and contribute instructions back to the project.

You can download the JBoss application server from the following link. We have only tested OpenEMPI against JBoss 4.2.3 although it may be supported on other versions as well. The instructions below assume that you have downloaded the 4.2.3 version of the application server which is currently available as jboss-4.2.3.GA.zip. Installation of the application server is as easy as expanding the zip file at an appropriate directory. In these instructions we assume the zip file is expanded under d:\servers\jboss-4.2.3.

This completes the installation of the application server software.

Installation of the OpenEMPI Software

First download the latest stable distribution from the site. Choose the appropriate archive format for your platform (.zip for Windows, .tar.gz for Unix). Unzip the contents of the distribution in some temporary location. The structure of the archive is as follows: 

     /openempi-${version}
       |
      openempi-${version}.ear
      openempi-core-${version}.jar
      openempi-openpixpdq-adapter-${version}.jar
      openempi-webapp-web-${version}.war
     /openempi-${version}/conf
           |
           create_database_schema.sql
           drop_database_schema.sql
           mpi-config.xml
           mpi-config.xsd
           jdbc.properties
           pixpdq_connectathon_patients.csv
           dataset_A_1000.csv

The top level directory contains various jar archives for deployment of OpenEMPI and the corresponding PIX/PDQ adapter.

  • openempi-${version}.ear is a standard J2EE ear file that can be used to deploy OpenEMPI on a J2EE application server. The rest of these instructions describe deployment of the ear file on the JBoss application server that was installed in the previous step. Keep in mind though that this is only one option for deployment of OpenEMPI.
  • openempi-core-${version}.jar contains all the core classes that comprise OpenEMPI and is the appropriate option if you want to deploy OpenEMPI embedded within another Java application.
  • openempi-webapp-web-${version}.war is a J2EE Web Archive that can be deployed against any compliant web container. It includes the core OpenEMPI infrastructure and API, the web-based administration console, and support for the PIX/PDQ interface. This is the best way to deploy OpenEMPI and get going as quickly as possible.
  • openempi-openpixpdq-adapter-${version}.jar is a jar file that comprises the adapter for deployment of OpenEMPI within the OpenPIXPDQ server. The adapter included in the distribution always matches the version of OpenEMPI that it is combined with. As OpenEMPI goes is improved over time, appropriate changes are needed to the OpenPIXPDQ adapter to take advantage of the enhancements made.
  • create_database_schema.sql is the database script to use for creating the database instance for OpenEMPI.
  • drop_database_schema.sql is the database script to use to drop all the database objects from the OpenEMPI schema
  • mpi-config.xml the configuration file that controls the operation of OpenEMPI. There is an XML configuration file included with the ear file distribution but the configuration file is included here separately for reference purposes.
  • mpi-config.xsd the schema file for validation of the OpenEMPI configuration file.
  • jdbc.properties is a sample properties file for configuring access to the database repository for OpenEMPI. If you are not using the

default instance name, database server, port number, etc for OpenEMPI, you can make the modifications in this file and then update the contents of the war or ear files using the jar command.

  • pixpdq_connectathon_patients.csv, dataset_A_1000.csv are sample datasets for testing OpenEMPI and getting started. The dataset_A_1000.csv is a sample patient dataset we got from the excellent Febrl project. You can use these patients for testing alternative matching or blocking algorithms or just to populate the patient registry and see what OpenEMPI has to offer. The pixpdq_connectathon_patients.csv file, as the name implies, is a list of patients that you can use to run the PDQ suite of tests that were used for preparation of OpenEMPI in getting tested as part of the OpenPIXPDQ service at the 2009 Connectathon. There is a complete suite of tests for both the PIX and PDQ interfaces included in the distribution. Documentation on how to run these tests will follow.

Create the Database Instance

If this is the first time that you are installing OpenEMPI on your system and have not created the database instance yet, this will be your first step. The Postgres 8.3 installation includes an administrative application called pgAdmin that should be located at d:\servers\postgres-8.3\bin\pgAdmin3.exe. Running the executable will bring up the GUI that allows you to connect to the database server. In order to connect to the server you will need to use the password that you assigned the postgres user when you installed the database server.

Before you create a schema for the new database instance, you need to create a user role. From the tree control on the left right click on "Login Roles" and select "New Login Role" from the menu. Create a new role named openempi and ensure the screen has the following information filled in.

To create a database instance for openempi right click on the Databases icon and select the "New Database.." link from the menu. In the dialog that comes up set the name of the new database to openempi and from the Owner drop down select openempi as the owner of the database. Now that the schema is in place, you need to add the database objects for openempi. In the Postgres Admin application select Tools->Query Tool from the menu. From the Query Tool select the File->Open menu option to open the sql script from the conf directory of the OpenEMPI 2.0 distribution. The name of the file is create_database_schema.sql. After loading the file execute the script which should successfully create all the database objects that are needed for OpenEMPI.

Once you have created the database and the openempi role, you can easily also run the database creation script from the command line using the psql command line tool. 

 $ cd conf
 $ psql -d openempi -U openempi -W
 Password for user openempi: ********
 openempi=# \i create_database_schema.sql
 openempi=# \dt 
                 Should list here all the database tables
 openempi=# \q
 $

Now that the database is configured you can deploy the application to the application server. This is as simple as copying the war file from the HOME directory where OpenEMPI was extracted as dist/openempi-webapp-web-${version}.war to the application server's deployment directory which is at d:\servers\jboss-4.2.3\server\default\deploy.

You should now be able to point your browser to the appropriate URL for your web server and get the login screen for the OpenEMPI administration application (for example: http://localhost:8080/openempi-admin/ should work on the JBoss/Tomcat server).

  • Mysql
  • Glassfish
  • Jruby
  • Rails
  • Nblogo
Terms of Use; Privacy Policy;
© 2010, Oracle Corporation and/or its affiliates
(revision 20100312.9442df5)
 
 
loading
Please Confirm