Cypress Validation Utility Custom Install Instructions

These instructions are for the Cypress Validation Utility (CVU) v3, which is not the latest version of the CVU. CVU v4 is not yet available in downloadable form, but can be accessed for non-PHI testing at https://cypressvalidator.healthit.gov.

The Cypress team recommends using the VM or Chef script unless you have a specific need or reason for a custom install.

The installation will require the installation of the following components

1. Setup and configure Ubuntu + Prerequisites

2. Fetching and configuring Cypress Validation Utility Source Code

3. Generate a Secret Token

4. Import the measure bundle

5. Configure Unicorn / Nginx

6. Setup and configure Ubuntu + Prerequisites

---

The first install steps are identical to the steps for installing regular Cypress. Please follow steps 1 - 6 in the Cypress 3.0 Custom Install Instructions and then return to these instructions.

2. Fetching and configuring Cypress Validation Utility Source Code

---

Install the additional dependencies for the application

sudo apt-get -y install nodejs

Getting the Cypress Validation Utility code

git clone https://github.com/projectcypress/cypress-validation-utility.git
cd cypress-validation-utility

Installing the version of ruby required for your cypress version

rbenv install 2.3.1
rbenv global 2.3.1

Installing the bundler gem in order to install the cypress dependencies

gem install bundler -v '1.12.5'

Installing the cypress dependencies

bundle install

Setup the cypress assets

bundle exec rake assets:precompile

3. Generate a Secret Token

---

This secret token is used by the cypress application throughout. This line sets up a "secret key" that's used to generate cookies. It's needed in multiple places in the app.

secret_key=`cat /dev/urandom | env LC_CTYPE=c tr -dc 'a-e0-9' | fold -w 128 | head -n 1`

4. Import the measure bundle

---

Cypress releases measure bundles that contain the measure artifacts that are needed to begin the certification process:

In addition to the measure bundle, the value sets need to be loaded into Cypress 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

Once you have an NLM user account, go to https://cypress.healthit.gov/measure_bundles. You will be prompted for your NLM credentials. Manually download the bundle called 'bundle-2015-alpha-20160623.zip'. Note the full path for the following steps:

At this point, you should still have a shell open as the cypress user.

Depending on the bundle version you wish to use, you will need to specify 2015-beta-20160707 (for the 2015 measures) 2016-beta-20160623 (for the 2016 measures) for the version flag. Replace BUNDLE_VERSION in the command below with your chosen bundle.

Run the following commands import the measure bundle

cd /home/cypress/cypress-validation-utility
bundle exec rake bundle:download_and_install version=BUNDLE_VERSION RAILS_ENV=production SECRET_KEY_BASE=$secret_key

5. Configure Unicorn / Nginx

---

The following commands will setup unicorn for you.

cat << CYPRESS_SITE_END | sudo dd of=/etc/systemd/system/cypress-validation-utility.service
  [Unit]
  Description=cypress-validation-utility

  [Service]
  Environment="SECRET_KEY_BASE=${secret_key}" "ENABLE_DEBUG_FEATURES=true" "DEFAULT_ROLE=" "RAILS_ENV=production" "BUNDLE_GEMFILE=/home/cypress/cypress-validation-utility/Gemfile"
  ExecStart=/home/cypress/.rbenv/shims/bundle exec /home/cypress/.rbenv/shims/unicorn --port 8001 config.ru
  ExecReload=/bin/kill -HUP \$MAINPID
  KillSignal=TERM
  User=cypress
  WorkingDirectory=/home/cypress/cypress-validation-utility
  Restart=on-failure

  [Install]
  WantedBy=multi-user.target
CYPRESS_SITE_END

Install nginx with the following commands:

sudo apt-get install -y nginx

You will then need to enable and start the service:

sudo systemctl enable cypress-validation-utility
sudo systemctl start cypress-validation-utility

The following set of commands will setup nginx for you.  Update the site configuration with:

cat << CYPRESS_SITE_END | sudo dd of=/etc/nginx/sites-available/cypress-validation-utility
  upstream primary {
    server localhost:8001;
  }

  server {
    listen 80;
    server_name _;

    root /home/cypress/cypress-validation-utility/public;

    try_files \$uri/index.html \$uri @app;

    location @app {
      proxy_pass http://primary;
      proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
      proxy_set_header Host \$http_host;
      proxy_redirect off;
    }

    error_page 500 502 503 504 /500.html;
    client_max_body_size 4G;
    keepalive_timeout 10;
  }
CYPRESS_SITE_END

Make the default nginx site be the cypress provided content:

sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/cypress-validation-utility /etc/nginx/sites-enabled/default

Restart nginx:

sudo systemctl restart nginx

To open the Cypress web app you'll need the server IP address from step 1.  The server IP address was found from the ifconfig command.  Open a web browser and enter

http://<server_ip_address>/

This should open the Cypress Validation Utility web application.