-
Notifications
You must be signed in to change notification settings - Fork 45
Installation v4.0 (Development Environment)
These instructions are for installing a development environment for the most up-to-date version of popHealth. For those who plans to do popHealth development and desires agility and not performance such as with working with large volume of data, then you can use these set of installation instructions. There is also a standard installation instruction - https://github.com/OSEHRA/popHealth/wiki/Installation-v4.0. The difference between the two installations is that the standard instructions use Phusion Passenger/Apache as the web application server. With the standard installation you gain significant performance via optimization provided by the Passenger / Apache application server.
The instructions are based on installing from the current master branch of the popHealth repository, which should be considered a work in progress until it's tagged with a version number.
Currently there are some compatibility issues with Firefox. Please use Chrome or IE for the best user experience.
You will need an NLM VSAC account to download value set definitions and finalize the installation of the VM. You can sign up for an NLM VSAC account at https://uts.nlm.nih.gov/home.html (click the "Sign Up" link in the upper right corner of the page.)
The instructions assume that a system user named 'pophealth' wants to install the app in their home directory. This is not a requirement; any user with sudo privileges can install pophealth. Just be sure to adjust the directory paths in the commands below.
The ISO for ubuntu 14.04 LTS can be downloaded from the following URL: http://releases.ubuntu.com/trusty/
These instructions were developed against the "64-bit PC (AMD64) server install CD" (ubuntu-14.04.2-server-amd64.iso).
Installing Ubuntu is a fairly straight-forward process, but for more details on installing Ubuntu please visit the following URLs:
Graphical install using the desktop CD: https://help.ubuntu.com/community/GraphicalInstall
Installation using the Alternate CD (more configuration options): https://help.ubuntu.com/14.04/installation-guide/index.html
Once Ubuntu has been installed you need to update the Apt packages. Apt is a software package management system used by Ubuntu. Note: the last command in the group below is only necessary if any packages were actually upgraded.
sudo apt-get update
sudo apt-get upgrade
sudo shutdown -r now
This step is only required if the server you are installing popHealth onto needs to go through an HTTP proxy server to reach the internet. These steps will ensure that the appropriate proxy settings are in place for every user that logs into the system.
Use your favourite text editor to create a file in /etc/profile.d named http_proxy.sh with the following contents. In the sample below, replace your.proxy.host.com with the fully-qualified host name of your proxy server, and your.proxy.port with the port number that the proxy server uses.
# Set up system-wide HTTP proxy settings for all users
http_proxy='http://your.proxy.host.com:your.proxy.port/'
https_proxy='http://your.proxy.host.com:your.proxy.port/'
export http_proxy https_proxy
Set proper permissions on the new file, and load the settings into the current environment. NOTE: the proxy settings will automatically be loaded when a user logs in, but we are manually loading them here, to avoid having to log out and log back in again.
sudo chmod 0644 /etc/profile.d/http_proxy.sh
source /etc/profile.d/http_proxy.sh
Make sure that the sudo command will allow the new proxy settings to be passed to commands it launches. This is done by using your text editor to create a file in the /etc/sudoers.d directory named http_proxy (no extension) with the following contents:
# keep http_proxy environment variables.
Defaults env_keep += "http_proxy https_proxy"
Set proper permissions on the new file:
sudo chmod 0440 /etc/sudoers.d/http_proxy
Git is a source control system. It will be used later to download the popHealth source code.
sudo apt-get install git-core
RVM is a system that allows managing different versions of Ruby. It will allow the correct version of ruby to be easily installed on the system. Ruby is the development language used for the popHealth application.
First we will need to install some dependencies:
sudo apt-get install build-essential openssl libssl-dev libreadline6 libreadline6-dev curl zlib1g zlib1g-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt-dev autoconf libc6-dev ncurses-dev automake libtool bison subversion pkg-config unzip
Next install RVM. This will install RVM for all users
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys D39DC0E3
curl -sSL get.rvm.io | bash -l -s stable
Source the RVM environment so we can use it here:
bash
source /usr/local/rvm/scripts/rvm
*****NOTE: If the above path does not exist, try replacing it with: ~/.rvm/scripts/rvm *****
Log out, and then log back in again so that the settings RVM installs will be loaded in your environment. Once you have logged back in, run the following commands. These will install some more dependencies.
We will install these dependencies using an admin console. The admin console can be opened with the following command:
sudo -i
Next we want to set the autolibs flag in rvm
rvm autolibs enable
Next we want to install Ruby 2.1.5 using RVM
rvm install 2.1.5
If you get a message about installing dependencies, press 'q'. We have already installed everything we will need.
Set ruby version 2.1.5 to be the default version:
rvm --default 2.1.5
Finally install bundler. Bundler is a Ruby Gem that allows downloading additional dependencies once we have the popHealth source code:
gem install bundler -v '1.7.2'
Close the admin console by running:
exit
setup rvm for the admin user:
source /etc/profile.d/rvm.sh
rvm use 2.1.5
rvm --default 2.1.5
*****NOTE: If the above path (/etc/profile.d/rvm.sh) does not exist, try replacing it with: ~/.rvm/scripts/rvm *****
MongoDB is the database used by popHealth. To install MongoDB run the commands:
sudo sh -c "echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' >> /etc/apt/sources.list"
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
sudo apt-get update
sudo apt-get install -y mongodb-org
To test connection (wait at least 15 seconds to let the db start up), run the command below. If the command exits with a error about not being able to connect, then reboot, and log back in as the admin user. Sometimes mongodb fails to create a network socket when it is started immediately after installation. It should automatically start when the system is rebooted.
mongo
This should output MongoDB shell version: 2.6.x
Note that the version must read 2.4.0 or later (at the time these instructions were written, the current release version of mongodb was 2.6.11).
Type 'exit' to exit the mongo shell
exit
Downloading the pophealth source code from github. The following commands assume that your current directory is located at /home/pophealth
git clone https://github.com/osehra/popHealth.git
cd popHealth
git checkout 2997442a1cbb45669dbaf30235bf71f0dc68af63
NOTE: If you get a message about "ruby-2.1.2 not being installed" when you cd into the popHealth directory, open the '.ruby-version' file in the popHealth directory (e.g.: sudo nano ./.ruby-verion) and change the version number shown to the version of ruby specified previously in step 4 of these directions.
Install popHealth and all its dependencies:
bundle install
popHealth releases measure bundles that contain the measure artifacts that are needed to begin the measure calculation process:
In addition to the measure bundle, the value sets need to be loaded into popHealth from the NLM VSAC Service. You will need an NLM account in order to complete this step and load value sets from the VSAC service._ Register for an account at: https://uts.nlm.nih.gov/home.html
Run the following command to download and install the measure bundle
bundle exec rake pophealth:download_update_install version=2.6.0 RAILS_ENV=development
popHealth has two modes - 'Multiple Practice mode', and 'Regular mode'.
The 'Regular mode' functions the same way popHealth has been functioning to date.
The 'Multiple Practice mode' is for users that want to report on multiple organizations at once, and have aggregate report capabilities. This mode allows multiple sites/groups/practices/clinics in the same instance of popHealth, while segregating the data through user accounts and role based access.
The popHealth instance is set to 'Regular Mode' by default. To switch to the 'Multiple Practice mode', please do the following:
In the file popHealth.yml which resides in the config folder in the application directory, (filepath - config/popHealth.yml), change the line
use_opml_structure: true
to
use_opml_structure: false
Save and close the file. More information about 'Multiple Practice mode' and role-based access can be found in the Pull request here - https://github.com/OSEHRA/popHealth/pull/10
***Switching from one mode to another is not supported and may cause issues with the application. If you want to switch from one mode to the other, you have to first empty the collections for providers, patients, users, practices, and the caches from MongoDB, and then proceed with #9.
To create the default admin user account, run the following command:
bundle exec rake admin:create_admin_account RAILS_ENV=development
Default Username: pophealth, Password: pophealth
You can change the account password once you log in and go to the 'Edit Account' page from the top right menu.
Certain tasks such as calculating measures and importer records are handled via a set of job queues and background worker processes that must be running in order for the application to function correctly. The tasks are placed into one of three different queues, calculation, rollup, or import. The simplest means to run these tasks is to use a single worker that will execute all of the jobs as they are added to the queue. This can be done by executing the following command.
bundle exec rake jobs:work RAILS_ENV=development
This will start a single worker in the foreground that will execute all tasks regardless of the queue that they are placed in.
As popHealth is using Delayed Job as the background processing library a number of separate workers can run and configured to work off specific queues. Below is an example of how to start a number of workers for each of the different queues. Please bear in mind that you will need to ensure that the --pid-dir setting for each is different and that the directory has been created in advance.
script/delayed_job start -n 1 --pid-dir=tmp/pids/calculation --queue=calculation
script/delayed_job start -n 2 --pid-dir=tmp/pids/rollup --queue=rollup
script/delayed_job start -n 2 --pid-dir=tmp/pids/import --queue=patient_import
For further information on Delayed Job please consult the documentation which can be found here https://github.com/collectiveidea/delayed_job.
Starting the application is very simple by running the following command from within the applications root directory.
bundle exec rails s -p <port>
This will start the application running on the port given in the command. If the -p option is left off then the application will start on the default port of 3000. Once started you will be able to access the app in a browser by navigating to http://localhost:. From there click on the "Create New User" link to add a new user to get started with popHealth.
There are two methods for importing patient data into popHealth - manual upload of patient file via the popHealth UI or patient API upload via http post. For testing purpose, you can download a test QRDA CAT I patient zip file derived from the Cypress tool version 2.6.1 and manually import the zip file using the popHealth administrator user interface. The test patient zip file can be accessed from https://github.com/OSEHRA/cqmtest/raw/master/cypress2.6-OSEHRA-popHealth/patient_qrda_pophealth.zip. To import, login into the popHealth application. The import function is located under the Administrator->Patients menu at the top right corner of the user interface. After the import, you should see a total of 56 patients loaded. To perform the CQM calculation, go to the Administrator->Providers menu, and select "Orphan" provider. This will take you to the CQM dashboard. Select any CQM to perform the CQM calculation.