PDC Gateway Server
This document outlines the steps required to set up the connection between the EMR Adapter and PDC Gateway as well as the setup of the PDC Gateway itself.
Since the EMR Adapter/Exporter will export E2E documents in plaintext, we require some form of encryption and protection around the document payload. This is done with an SSH tunnel connecting the EMR Adapter to the PDC Gateway Server. The tunnel is achieved with OpenSSH if the EMR Adapter is on unix, and MyEnTunnel on windows.
Since we want this to be automated, we can't have authentication happen via a passphrase since that will require human intervention, not to mention insecure. To do this, the Gateway must know the public key of the EMR Adapter. This can be done by generating an RSA 2048 bit keypair on the EMR Adapter system, and copying the generated public key over to the PDC Gateway's authorized_keys file in the .ssh folder.
Most installations of unix based operating systems will have OpenSSH by default. Setting up the SSH tunnel is very straightforward - it only involves mapping a local port to be forwarded to the Gateway. Make sure to keep the tunnel going at all times by having it fire frequent keep-alive packets and having it reconnect on server startup or fault.
Running something like the following will make the system listen to local port 3001 and forward it to the Gateway at port 13001.
ssh -L 3001:localhost:13001 <gateway hostname>
For more background information on SSH port forwarding, visit the ubuntu community wiki.
Windows does not have OpenSSH by default. We rely on a software package called MyEnTunnel (found here). MyEnTunnel is a wrapper around the PuTTY software group - specifically plink in order to create and maintain the SSH tunnel.
MyEnTunnel Configuration
After installing MyEnTunnel, ensure that the program will start up with the computer. This is to make sure we can get a tunnel set up automatically as soon as the computer finishes booting. This can either be done by placing a shortcut into the Startup folder, or adding an entry into the registry.
Afterwards, open the program, and on the Settings tab, set the ssh server field to the PDC Gateway's ip address or domain name, and the port name to whatever it is set up to. The username should be the account the ssh tunnel will login as, and the passphrase should be blank since we're using a keypair for ssh authentication. Ensure that the private key file (likely a .ppk extension) be transfered over to the folder that MyEnTunnel is located, and have the filename be called "keyfile.ppk".
On the settings menu, you will want the following only to be checked in:
- Connect on Startup
- Prompt on Exit
- Enable Compression
- Reconnect on Failure
- Infinite Retry Attempts
- Use Private Key
- Disable Notifications
Retry Delay should be set to 5 to signify a retry after 5 seconds.
On the tunnels tab, you will want to add a line for each port that needs to be forwarded from the EMR Adapter to the Gateway. For example, if you need port 13001 forwarded, add the line 13001:localhost:13001 which will make the EMR Adapter system listen to any traffic on port 13001 locally and forward it to the Gateway.
Afterwards, click save, and attempt to connect. If it connects and reports a stable connection, the tunnel should be properly set up.
Since we will have only one physical PDC Gateway but still require one logical gateway per clinic, the PDC Gateway will host a number of virtual machines. Every virtual machine will be as lightweight as possible, containing the hQuery Gateway software and the mongodb backend as well as the supporting environments such as ruby and rails. In order to minimize maintenance and scalability issues, Vagrant will be used to spin up and maintain these virtual machines.
In order for the PDC Gateway to do this, the machine needs to be running Ubuntu 12.04 LTS x64 and have all of its security updates. Vagrant and VirtualBox need to be installed as well, and can be done with sudo apt-get install vagrant and sudo apt-get install virtualbox. It should be noted that the BIOS of the server should have hardware virtualization enabled in order to allow 64 bit VMs to run.
Once the supporting software is installed, clone a copy of the scoophealth/devops public repository to the PDC Gateway server. Inside that repository, there should be a directory called Vagrant. For every virtual machine that needs to be spun up, there needs to be a fresh copy of that folder deployed.
Copy that Vagrant folder and save it somewhere standard. Something like ~/vagrantgateways/gateway_01 or some other predictable naming scheme is recommended.
For every individual gateway vm, you will need to update the port that virtual machine will listen to and forward. To do this, open up the Vagrantfile, and replace the following line with something else. For example, if you want the VM to listen to port 13005, change the following line from
config.vm.network "forwarded_port", guest: 3001, host: 13001
to
config.vm.network "forwarded_port", guest: 3001, host: 13005
Save that file with the change. To start up the virtual machine, run
vagrant up
This process will start up the VM, and set up the internal environment to have the gateway set up and ready to deploy. The provisioning process may take anywhere from 5-15 minutes. It will generally take a while when compiling the Ruby runtime required for hQuery Gateway.
Once it is done provisioning, the VM will be up, but the actual gateway software has not started yet. As of 3/24/2014, you will need to manually start up the server in the vagrant VM. To do that, perform the following commands:
vagrant ssh
This will log you into the vagrant VM.
cd endpoint/query-gateway
screen
Press enter to acknowledge the message.
./runme.sh
After it appears the server has started press ctrl+a then ctrl+d to detach from the screen session. You may then exit the vagrant vm, and the gateway should be ready to serve a new clinic. At this point, you should be back onto the main gateway server command prompt screen.
To stop the deployed VM, issue a vagrant halt and the VM should shut itself down. Rebooting the VM just requires another vagrant up command.
If the gateway is no longer wanted, the VM instance can be destroyed with vagrant destroy. This will delete the VM instance entirely, including the patient data within.
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
