Gateway Hub Setup
Written by Jeremy Ho. Last edited: 7/10/2013
This setup guide creates an Ubuntu 12.04.1 LTS Virtual Machine with either the SCOOP Gateway components or SCOOP Hub components. Although this guide is designed to help a user quickly get the SCOOP machines set up, this is by no means the only way to install the components.
In order to be successful with this guide, it is assumed that you are comfortable working with Linux, the command line, and text editor. Any text that appears inside a lightly colored box is a command that needs to be executed in the terminal. Remember that although copy is Ctrl+C, to paste in the terminal (at least for Ubuntu) you need to do Shift+Ctrl+V in order to paste. Anything that is in italics is an installation related note, and anything that is in an indented bullet is a comment.
At the time of writing, these are the software versions we are currently using and know should work.
- Ubuntu 12.04.1 LTS x64
- VirtualBox 4.2.6 r82870
- Git 1.7.9.5
- Ruby 1.9.3
Download and install VirtualBox from virtualbox.org
Create a new Virtual Machine and set Virtual Machine to 2GB RAM, 200GB HD.
- Select the VDMK format if you think you may transfer this VM to VMWare down the road. Otherwise the VDI format works as well.
Download and install the Ubuntu 12.04.1 LTS x64 Desktop Operating System.
- You can get the iso from releases.ubuntu.com/12.04.1/. Select the ubuntu-12.04.1-desktop-amd64.iso image from their site.
These instructions apply for both the SCOOP Gateway and SCOOP Hub machine installations. These prerequisite components must be installed before installing the specific components of SCOOP.
Since OSCAR and Tomcat are built on Java, we require the Java JDK.
Note: We want to have the Java JDK released by Oracle, not the OpenJDK version.
Note 2: Try Option 1 first. If that doesn't work, try Option 2.
Note 3: If neither options work, refer to the Alternative Oracle JDK Installation Notes.
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java6-installer
cd ~
wget https://github.com/flexiondotorg/oab-java6/raw/master/oab-java.sh -O oab-java6.sh
chmod +x oab-java6.sh
sudo ./oab-java6.sh
sudo apt-get update && sudo apt-get install sun-java6-jdk
Since the SCOOP components depend on Ruby, Rails, and MongoDB, we will need to make sure they are properly installed as well as their subcomponents. Specifically, the following lists the requirements needed for hQuery to run properly. Also note that should you wish to have multiple terminal windows to maintain the multiple running components of hQuery, it would not be a bad idea to consider using Screen for that purpose. You can install screen with the following command:
sudo apt-get install screen
SCOOP Dependencies
- Ruby 1.9.3
- Rails 3.2
- MongoDB 1.8.1+
- Mongoid 3.0+
The following instructions offer the least painful method of rapidly getting an installation of Ruby and Rails installed.
sudo apt-get install curl
curl -L https://get.rvm.io | bash -s stable
Update the Terminal environment
source ~/.rvm/scripts/rvm
Then to check for Ruby requirements, the following command will let you know which packages are needed.
rvm requirements
Normally this will automatically install all the dependencies that RVM requires, but if not, look in the output for a paragraph with "Additional Dependencies:". It should provide an apt-get command with a list of dependencies. Go ahead and run what it suggests to install the missing dependencies.
We want Ruby version 1.9.3 so the following installs that version.
rvm install 1.9.3
rvm use 1.9.3 --default
We also need a packager for Ruby to run some things.
rvm rubygems current
gem install bundler
Lastly, we require Rails to run some of the server instances.
gem install rails
It may be necessary to update the version of ruby installed periodically. To do that, make sure your RVM (Ruby Version Manager) is up to date.
rvm get stable
rvm reload
Afterwards, you can ask RVM to list the ruby versions available. Check to see if your desired update is listed.
rvm list known
Afterwards, just reinstall the ruby version and it should update with some prompts.
rvm install 1.9.3
The SCOOP components use MongoDB to store the data. In order to install this, we must let Ubuntu know of another repository to pull from. You will need root rights for this.
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10
echo 'deb http://downloads-distro.mongodb.org/repo/ubuntu-upstart dist 10gen' | sudo tee /etc/apt/sources.list.d/10gen.list
Update Ubuntu's repository to also pick up the new repository data, and then install the latest version of MongoDB.
sudo apt-get update
sudo apt-get install mongodb-10gen
SCOOP Components will either reside on the Gateway Server (under the practitioner's control), or the Hub Server (under the researcher's control). For reference, the port numbers for all the components can be found here:
Component Port Numbers
- relay-service.rb | 3000
- Query Gateway | 3001
- Query Composer | 3002
To get a copy of the relay service, do the following:
cd ~/workspace
wget https://github.com/scoophealth/SCOOP-doc/wiki/files/relay-service.rb
chmod +x relay-service.rb
Look for the line Dir.glob('/vagrant/files/*.xml') do |xml_file| and change the /vagrant/files/ to your own folder where the patient documents are stored at.
To run the server, just run with ruby. You may want to consider using a screen terminal if you intend on having the server run after you log off.
./relay-service.rb
First we need to get the source code for the gateway. We do this with the following:
cd ~/workspace
git clone git://github.com/scoophealth/query-gateway.git
Note: Depending on the development status of SCOOP, you may need to checkout and build on the scoop-develop branch instead of master
If you plan on editing the code, make sure you use an SSH version of the remote instead.
Afterwards, you will want to go into the new directory, install, seed, and start the server.
cd query-gateway
bundle install
bundle exec rake db:seed
mkdir -p tmp/pids
The following commands starts the server. If you want, you may create a bash script that automates this for you. You may want to consider using a screen terminal if you intend on having the server run after you log off.
##!/bin/bash
bundle exec script/delayed_job start
bundle exec rails server -p 3001
bundle exec script/delayed_job stop
First we need to get the source code for the gateway. We do this with the following:
cd ~/workspace
git clone git://github.com/scoophealth/query-composer.git
Note: Depending on the development status of SCOOP, you may need to checkout and build on the scoop-develop branch instead of master
If you plan on editing the code, make sure you use an SSH version of the remote instead.
Afterwards, you will want to go into the new directory, install, and start the server.
cd query-composer
bundle install
mkdir -p tmp/pids
The following command starts the server. If you want, you may create a bash script that automates this for you. You may want to consider using a screen terminal if you intend on having the server run after you log off.
##!/bin/bash
bundle exec script/delayed_job start
bundle exec rails server -p 3002
bundle exec script/delayed_job stop
You can access this server's page by going to http://localhost:3002. There you must create an account. Fill out the new user form and submit it. Afterwards, we need to activate the account as an admin. We do that with the following command:
bundle exec rake hquery:users:grant_admin USER_ID=<USERNAME>
Where is replaced by the username you used to sign up.
Sometimes a system will need all of its gems cleared out. To do that, run the following:
gem list | cut -d" " -f1 | xargs gem uninstall -aIx
This will grab all the existing gems, and tell them to be uninstalled. Afterwards, you can simply bundle install to grab only the gems you need.
This section contains old installation instructions for software packages that SCOOP is no longer using in its architecture. They remain here for archival reasons.
Install Mirth Connect v2.2.1.5861. (As of 7/24/2012). This is available for download from http://www.mirthcorp.com/community/downloads
Select the Installer entry under the Linux table. Alternatively, you may do the following to download directly:
cd ~
wget http://downloads.mirthcorp.com/connect/2.2.1.5861.b1248/mirthconnect-2.2.1.5861.b1248-unix.tar.gz
Afterwards, extract Mirth Connect, go into the Mirth Connect directory, and start its service. It will bind to port 8080.
tar -xzvf mirthconnect-2.2.1.5861.b1248-unix.tar.gz
cd Mirth\ Connect
./mcservice start
Connect to http://localhost:8080 to start the Java Applet and begin configuration.
Configuration instructions for Mirth may be found by going to IT0 Configuration or to the respective Iteration Configuration you want to implement.
OSCAR MySQL Access Update
Since you are going to be accessing OSCAR's database directly, you need to let the database know to allow your SCOOP Gateway access. On the OSCAR Server, do the following:
Backup the MySQL configuration for safety
sudo cp /etc/mysql/my.cnf /etc/mysql/my.cnf.bak
Then open up the file:
sudo vi /etc/mysql/my.cnf
Comment out this line by adding a # before the following line:
bind-address = 127.0.0.1
Save and then restart the MySQL server
sudo /etc/init.d/mysql restart
Log into the MySQL database and do the following where "mirth" is the user, "host" is your server hostname or IP, and xxxx is the database password:
grant all privileges on *.* to mirth@host identified by "xxxx";
Make MySQL update the privileges:
flush privileges;
First we need to get the source code for the rest adapter. We do this with the following:
cd ~
git clone git://github.com/scoophealth/mirth-rest-adapter.git
Afterwards, you will want to go into the new directory, install, configure, and start the server.
cd mirth-rest-adapter
We need to update a line in the configuration file "records_controller.rb". You can open it with this command:
vi ~/mirth-rest-adapter/app/controllers/records_controller.rb
Update this line to reflect this:
url = URI.parse('http://localhost:3001/records/create')
Save, and then install this component.
bundle install
We also need to update the Gemfile to add execjs and therubyracer.
vi Gemfile
Find this line: gem 'bundler', '1.2.0.pre.1' and add the following lines after it:
gem 'execjs'
gem 'therubyracer'
Then change the following line:
gem 'bundler', '1.2.0.pre.1'
to the following (this removes the version requirement):
gem 'bundler'
The following command starts the server. If you want, you may create a bash script that automates this for you.
bundle exec rails server -p 3000
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
