Installation v5.1

peter li edited this page May 2, 2018 · 2 revisions

These instructions are for installing the most up-to-date version of popHealth. 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.

There is also a development environment installation instructions. The difference between the two installations is that these set of instructions use Phusion Passenger/Apache as the web application server. With this installation you gain significant performance via optimization provided by the Passenger / Apache application server. For those who wants to try out popHealth and is concerned with the system performance of popHealth, you should use these set of instructions.

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

1. Installing Ubuntu

The ISO for ubuntu 16.04 LTS can be downloaded from the following URL:

These instructions were developed against the "64-bit PC (AMD64) server install CD" (ubuntu-16.04-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:

Installation using the Alternate CD (more configuration options):

Once Ubuntu has been installed you need to update the software on the computer using Apt. 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 -y upgrade
sudo reboot

2. Configure Proxy Settings

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 with the following contents. In the sample below, replace 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
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/
source /etc/profile.d/

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

3. Installing Git

Git is a source control system.  It will be used later to download the popHealth source code.

sudo apt-get install -y git-core

4. Installing RVM and Ruby 2.2.5

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:// --recv-keys D39DC0E3
curl -sSL | sudo bash -l -s stable

Source the RVM environment so we can use it here:

source /usr/local/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.2.5 using RVM

rvm install 2.2.5

If you get a message about installing dependencies, press 'q'.  We have already installed everything we will need.

Set ruby version 2.2.5 to be the default version:

rvm --default 2.2.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.14.6'

Close the admin console by running:


setup rvm for the admin user:

source /etc/profile.d/
rvm use 2.2.5
rvm --default 2.2.5

*****NOTE: If the above path (/etc/profile.d/ does not exist, try replacing it with: ~/.rvm/scripts/rvm *****

5. Installing MongoDB

MongoDB is the database used by popHealth.  To install MongoDB run the commands:

echo "deb trusty/mongodb-org/3.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.0.list
sudo apt-key adv --keyserver hkp:// --recv 7F0CEB10
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo wget -O /etc/systemd/system/mongod.service
sudo systemctl start mongod
sudo systemctl enable mongod

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.


This should output MongoDB shell version: 3.0.x

Note that the version must read 3.0.9 or later.

Type 'exit' to exit the mongo shell


6. Downloading PopHealth source code

Downloading the pophealth source code from github. The following commands assume that your current directory is located at /home/pophealth

git clone popHealth
cd popHealth

Install popHealth and all its dependencies:

bundle install

Install bower

sudo apt-get install nodejs
sudo apt install nodejs-legacy
sudo apt-get install npm
sudo npm install -g bower
rm -rf vendor/assets/components/*
bower install

7. Import the measure bundle

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:

Note before you install the 2017 measure bundle, make sure to run the following command in Mongo. It will allow the measure bundle to get installed without stopping, else you will get an "Index Key Too Long" error.

> db.adminCommand( { setParameter: 1, failIndexKeyTooLong: false } )
> exit

Run the following command to download and install the measure bundle

bundle exec rake pophealth:download_update_install version=2017 RAILS_ENV=production

Note that if you are working with the certification body such as InfoGard, please make sure to ask which measure bundle is used to generate the Cypress test deck. We have discovered that InfoGard is currently using 2017.0.1 bundle for their tool; therefore, you will need to set the version number to 2017.0.1 instead of 2017

After executing the above command, make sure that the following responses are displayed on the screen to show that the measure bundle i.s installed without any issue.

Successfully imported bundle at: bundles/

Imported into environment: PRODUCTION Loaded all measures Sub-Measures Loaded: 108 Test Patients Loaded: 383 Extensions Loaded: 2 Value Sets Loaded: 757 Cleaning out records and caches

8. Configure popHealth mode

popHealth has two modes - 'Multiple Practice mode', and 'Regular mode'.

The 'Regular mode' functions the same way popHealth has been functioning since it was created by Mitre for use by a single organization.

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 'Multiple Practice Mode' by default. To switch to the 'Regular 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: false


use_opml_structure: true

Save and close the file. More information about 'Multiple Practice mode' and role-based access can be found in the Pull request here -

***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 #7.

10. Creating an administrator user account

To create the default admin user account, run the following command:

bundle exec rake admin:create_admin_account RAILS_ENV=production

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.

11. Configure Startup Processes

Please note that the following scripts from step 11 to 13 assumes that the pophealth code are located at /home/pophealth/popHealth. Please modify the script accordingly if the code are placed at a different location

Configure delayed job to start up on server startup. At this point, you should still have a shell open as the pophealth user:

cd ~
echo -e '#!/bin/bash\ncd /home/pophealth/popHealth\n. /usr/local/rvm/scripts/rvm\nbundle exec rake jobs:work RAILS_ENV=production\n' >
chmod +x

cat << DELAYED_WORKER_END | sudo dd of=/etc/systemd/system/pophealth_delayed_worker.service



You will then need to start and enable the service:

sudo systemctl enable pophealth_delayed_worker
sudo systemctl start pophealth_delayed_worker

12. Precompile Assets

To set up the asset pipeline and make sure all the images and fonts are included, run the following from the application directory

cd popHealth
rake assets:precompile RAILS_ENV=production RAILS_RELATIVE_URL_ROOT=/home/pophealth/popHealth

13. Configure Passenger / Apache

Install apache and passenger with the following commands:

sudo -i
apt-get install apache2=2.4.*
gem install passenger -v '5.1.2'

These should be the dependencies required for passenger:

apt-get install libcurl4-openssl-dev apache2-prefork-dev libapr1-dev libaprutil1-dev

Install the apache passenger module.  If you need other dependencies, the installer will tell you:


The end of the passenger apache module install will tell you to edit two files.

The following set of commands will do those edits for you.  Update the site configuration with (please note that the script below assume that the pophealth code is installed on /home/pophealth/popHealth):

cat << POPHEALTH_SITE_END > /etc/apache2/sites-available/pophealth
 <VirtualHost *:80>
   PassengerRuby /usr/local/rvm/wrappers/ruby-2.2.5/ruby
   DocumentRoot /home/pophealth/popHealth/public
   TimeOut 1200
   <Directory /home/pophealth/popHealth/public>
      AllowOverride all
      Options -MultiViews
      Require all granted

Make the default apache site be the pophealth provided content:

rm /etc/apache2/sites-enabled/000-default*
ln -s ../sites-available/pophealth /etc/apache2/sites-enabled/000-default.conf

Update the apache configuration with the following commands:

cat << POPHEALTH_MOD_END > /etc/apache2/conf-available/pophealth
SetEnv SECRET_KEY_BASE `cat /dev/urandom | env LC_CTYPE=c tr -dc 'a-e0-9' | fold -w 64 | head -n 1`

ln -s /etc/apache2/conf-available/pophealth /etc/apache2/conf-enabled/pophealth.conf

cat << PASSENGER_CONF_END > /etc/apache2/mods-available/pophealth.conf
LoadModule passenger_module /usr/local/rvm/gems/ruby-2.2.5/gems/passenger-5.1.2/buildout/apache2/
<IfModule mod_passenger.c>
   PassengerRoot /usr/local/rvm/gems/ruby-2.2.5/gems/passenger-5.1.2
   PassengerDefaultRuby /usr/local/rvm/gems/ruby-2.2.5/wrappers/ruby

ln -f -s /etc/apache2/mods-available/pophealth.conf /etc/apache2/mods-enabled/pophealth.conf

Restart apache:

service apache2 restart

Exit the root shell:


To open the popHealth web app you'll need the server IP address. Open a web browser and enter


14. Importing test patients

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 3.1 and manually import the zip file using the popHealth administrator user interface. The test patient zip file can be accessed from

Unzip the patient zip file. You will find a series of zip files for each of the measures used for the Cypress attestation. 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. Assuming that you are using the "Multiple Practice" mode, first create a practice, then select the newly created practice when importing a specific patient zip file for a given measure. After the import, you should see a total of a number patients loaded. To perform the CQM calculation, go to the Administrator->Providers menu, and select the practice provider. This will take you to the CQM dashboard. Select reporting period from 1-1-2016 to 12-31-2016 and the CQM associated with the patient file to perform the eCQM calculation. Note that the test patient data contain patient encounters dated in 2016 hence you will only see results if the reporting period is set to 2016.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.