Installation v1.4

Installing PopHealth from Code

Dependencies

Git

You will first need to install the Git version control system on your machine, in order to download the popHealth source code packages. Instructions for installing Git on your system and platform are available here

###Ruby 1.9.2

popHealth requires the use of the Ruby 1.9.2 or higher programming language. Instructions for installing Ruby are available here

###JRuby 1.6.2

The software that imports data into the popHealth database requires the use of the JRuby 1.6.2 or higher. Instructions for installing JRuby are available here

###Bundler

Once you have installed all the dependency utilities, you will need to install Bundler, the application dependency management tool. To install Bundler, run the following command:

gem install bundler

###MongoDB

popHealth requires the use of the MongoDB open source, document-based database. To use popHealth, you will need to have installed MongoDB 2.0.1 or higher prior to downloading the popHealth code. Instructions for installing MongoDB are available here. As part of the setup process of MongoDB, you should also ensure the Mongo 'bin' directory is in your operating system's PATH environment variable.

###Redis

popHealth relies on Redis for background jobs via Resque. To install Redis, please refer to:

http://redis.io/download

You can also find information on Redis at the Resque homepage. Resque is used by this project to calculate quality measures in background jobs. We also use resque-status. Please consult the resque-status instructions for working with the resque-web application if you would like to use it to monitor status.

###Installing popHealth

Once you have installed of the dependency utilities and libraries, you will be able to download and install the popHealth software source code. At a minimum, there are two core modules which you will need to install to get popHealth up and running. These are the quality measure definitions, and the popHealth web application. An overview and installation instructions for installing these software modules is detailed below.

####popHealth Quality Measure Definitions

All of the popHealth Quality Measure Definitions are defined in a separate repository. To begin the process of downloading and installing popHealth, you should first download the measure definitions from the associated measures repository.

git clone git://github.com/pophealth/measures.git

If you intend on making any contributions to the popHealth project, you will be required to use a fork of the popHealth Git repository. To do this, you will need to create an account on GitHub, and create a fork of the measure repository. Instructions for creating a GitHub account are available here. Once you have created a GitHub account, you will be able to create a fork of of the measure repository off of the repository website here

Additionally, you should ensure that all of the latest dependencies for the measures, have been managed and installed by bundler. To do this, change your file system directory to the new measures repository and issue the following command on your console:

cd measures
bundle install

####popHealth Web Application

Once you have installed the Quality Measure Definitions, you will need to install the popHealth application to view an report your results from popHealth. To begin the process of downloading and installing popHealth, you should first download the measure definitions from the associated measures repository.

git clone git://github.com/pophealth/popHealth.git

If you intend on making any contributions to the popHealth project, you will be required to use a fork of the popHealth Git repository. To do this, you will need to create an account on GitHub, and create a fork of the popHealth repository. Instructions for creating a GitHub account are available here. Once you have created a GitHub account, you will be able to create a fork of of the popHealth repository off of the repository website here

#Testing and Startup

##MongoDB

You will need to ensure that your MongoDB database is running on your system. To startup the MongoDB daemon, assuming you have setup your PATH environment variable correctly to include the MongoDB bin directory, you should be able to run the following command from your console:

mongod

To verify that your instance of MongoDB is working, you should be able to open up another console, and type in the following command:

mongo

Which should return the following result:

MongoDB shell version: 1.8.1
connecting to: test
>

If you are using popHealth in an operational setting with live patient records, we strongly advise users to change the user name and password credentials on your MongoDB server, to prevent accidental or malicious use of the patient data in your instance of popHealth. Instructions for configuring stronger security relating to user name and password credentials are available via the MongoDB website.

##Redis

redis-server

##Resque Workers

popHealth will kick off background jobs with Resque. For these jobs to to actually get performed, you need to be running resque workers. This can be done with the following run from the popHealth web application directory:

cd popHealth
QUEUE=* bundle exec rake resque:work

##Test Quality Measure Patient Records

On the measures repository, there are several utilities to allow for testing the popHealth software, and for generating randomized test patient records to ensure that the popHealth database, web application, and measure definitions are properly working. To perform this test, and generate 500 patient records with a reporting period ending on December 31, 2010, issue the following commands over your console:

cd measures
bundle update
export DB_NAME=pophealth-development
bundle exec rake mongo:reload_bundle
bundle exec rake patient:random[500]

##Test popHealth Web Application

Once you have updated your MongoDB database with test data, you will need to starup

cd popHealth
bundle install
bundle exec rails server

When the popHealth web application startup scripts have finished, you should open up a web browser (FireFox 3.5 or higher, Internet Explorer IE 7 or higher, and Safari 4 or higher). For more information about browser compatibility with the popHealth web application view the FAQ section on the popHealth website http://projectpophealth.org/faq.html#browsers

##Populating C32 Records

###C32 and CCR Data Importer

If you plan on importing patient records that have been represented via the C32 or CCR XML format, you should have collected all of your patient records and placed them in a directory on your system's file system. Once you have completed this task, you can begin the process of importing the C32 data into popHealth. You will need to have installed the measures, and have instantiated the popHealth web application prior to starting this. Additionally, you should have your instance of the popHealth web application up and running before starting this process. To download this code, issue the following command:

git clone git://github.com/pophealth/pilot-toolkit.git

This component of the project needs to be run using JRuby. This allows for easy XML schema validation and running XSLT on any platform. This project also uses and distributes .jar files for working with XML via Saxon. To make sure that you can run the code correctly, you must set a CLASSPATH environment variable to ensure that Saxon is loaded into the execution environment. This can be done by issuing the following command:

export CLASSPATH=jars/saxon9.jar:jars/saxon9-dom.jar:jars/commons-codec-1.4.jar:jars/commons-logging-1.1.1.jar:jars/httpclient-4.1.1.jar:jars/httpclient-cache-4.1.1.jar:jars/httpcore-4.1.jar:jars/httpmime-4.1.1.jar:jars

Once you have done that, and assuming you have installed and verified that JRuby has been properly setup, you can start the C32 importer user interface via the following command:

jruby lib/start_importer.rb

Once the popHealth C32 importer user interface starts up, you should select a directory from the file menu where all of your C32 XML files have been exported. Once you have selected this directory, all of the files in that directory will be displayed in the C32 importer user interface. You can now select the "Import" button on the bottom of the user interface. Each C32 record in the directory will be analyzed for compliance against the C32 standard, and uploaded to the popHealth database via a RESTful service on the web application.

After all the C32 records have been uploaded to the popHealth database, you should be able to view the web application by starting up a browser and visiting http://127.0.0.1:3000. This assumes that you have not altered the web application with the introduction of https, or changed the port number, or performed any additional administrative configuration tasks that would be expected for deploying popHealth in a production setting.

###Removing and re-setting popHealth patient records

If you need to remove and re-set the patient records that have been represented via the C32 or CCR XML format, issue the following commands from your 'measures' repository:

rvm use 1.9.2
export DB_NAME=pophealth-development
bundle exec rake mongo:drop_records