Gateway Hub Setup
Written by Jeremy Ho. Last edited: 2/13/2014
This setup guide creates an Ubuntu 12.04.3 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. We also have some documentation for deploying a gateway instance onto a Windows platform. Although the gateway software supports windows, that platform isn't as well supported as linux.
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.3 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.3 LTS x64 Desktop Operating System.
- You can get the iso from releases.ubuntu.com/12.04.3/. Select the ubuntu-12.04.1-desktop-amd64.iso image from their site.
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
At the time of writing, these are the software versions we are currently using and know should work.
- Windows NT Based OS
- Git 1.8.5.4
- Ruby 1.9.3
We have tested hQuery Gateway on Windows 7 and Windows Server 2008 R2. It should be supported on other NT based versions of windows, but we have not directly tested them. In general, any Windows OS environment will suffice.
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.
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.
Visit http://rubyinstaller.org/downloads/ and download Ruby 1.9.3-p484, as well as the 1.9.3 development kit.
Direct Links:
DevKit-tdm-32-4.5.2-20111229-1559-sfx.exe
Run the Ruby Installer 1.9.3 program to install the ruby environment. Default settings work fine. If you run the following, you should expect to see ruby version 1.9.3.
ruby --version
Afterwards, run the DevKit and have it extract to somewhere permanent such as C:\ruby193\devkit. To set up the devkit, enter your devkit folder on command line (such as C:\ruby193\devkit) and run
ruby dk.rb init
This creates a config.yml file. It is not necessary to change that file. Afterwards, run
ruby dk.rb install
And this will install the devkit into your ruby environment. We also need a packager for Ruby to run some things.
gem install bundler
Lastly, we require Rails to run some of the server instances.
gem install rails
If no errors show up, the ruby environment is ready.
The SCOOP components use MongoDB to store the data. In order to install this, we need to download and install mongodb. Visit http://www.mongodb.org/downloads and download the Windows 64 bit version. Then expand it to somewhere like C:\mongodb.
At this point, you may wish to add C:\mongodb\bin to your PATH variable for convenience.
Create data and db folders on the root of your hard drive for mongo to store its database.
cd C:\
md data
md data\db
To redirect mongo's log to file we do the following:
cd C:\mongodb
md log
echo logpath=C:\mongodb\log\mongo.log > C:\mongodb\mongod.cfg
At this point, restart your console, and run mongod. If it starts up, everything is working, and you can run mongo to connect to it.
To have mongodb running as a service, run the following:
C:\mongodb\bin\mongod.exe --config C:\mongodb\mongod.cfg --install
net start MongoDB
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 or cd ~ on Windows
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 or md tmp and md 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
The source code includes convenient startup scripts called runme.sh for linux, and runme.bat for windows.
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.
The source code includes convenient startup scripts called runme.sh for linux.
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.
