OSEHRA VistA Development VM Installation

How to Setup OSEHRA VistA Development Virtual Machine (VM)

This instruction is designed for installation of the OSEHRA VistA on a VirtualBox virtual machine (VM) hosted in a Windows, OS X, or Linux operating system. See Rackspace Vagrant Configuration for installation on Rackspace VM or AWS EC2 Vagrant Configuration for installation on Amazon EC2 VM. The following diagram illustrates the interactions of various software components used during the installation process.

Tutorial Video

There is a tutorial video that demonstrates the installation process in a Windows environment on YouTube. This is highly recommended for new users to Vagrant or VistA.

Prerequisites:

  • Vagrant - Vagrant is an open source application that makes setting up development environments easy. It essentially is an automated virtual machine (VM) provisioner which can talk to a variety of providers (VirtualBox, Rackspace, AWS, etc.) to create a base VM and deploy the developed application within it. Go read more about the history of Vagrant here. We will use VirtualBox in the instruction below.
  • VirtualBox - VirtualBox is an open source virtual machine provider that works with Vagrant.
  • Git - Git is an open source distributed version control system that is incredibly popular for managing the source code of projects. You will need Git to download OSEHRA VistA repository.
  • OSEHRA VistA GitHub Repository – The OSEHR VistA repository contains all of the project specific files, such as source code, scripts, and documentations that will enable Vagrant to create the VistA installation.

Installation Steps:

  1. Install Vagrant. Download Vagrant from https://www.vagrantup.com/downloads.html and install to the host machine. You need to download the correct version of Vagrant for your operating system. Vagrant shows the operating system icons to the left of the links to make the choice easier.
  2. Install VirtualBox. Download VirtualBox from https://www.virtualbox.org/wiki/Downloads and install to the host machine. VirtualBox is an open source virtual machine provider that works with Vagrant. As with Vagrant above, select the correct binary package for your operating system. You do not need to download the Extension Pack or any other extra packages from VirtualBox. It is a simple installer that you can take the defaults through the installation process. Please note that VirtualBox will not run if the vt-x/amd-v hardware acceleration setting in the PC BIOS is turned off for x86 cpus.
  3. Install Git. Download Git from http://www.git-scm.com and install to the host machine. Select the correct version of Git for your operating system. Use the defaults through the installation process.
  4. Clone the VistA Repository. The VistA repository contains all of the project specific files for telling Vagrant what to do and how to do it. Open a git-bash prompt - look for git-bash in “All Programs” under the Start Menu (Windows) or a bash shell (Linux or Unix).

    NOTE: The guides assume that you will use a git-bash or a bash shell for all future interactions with Vagrant.

    You can clone the VistA repository anywhere but for simplicity we will clone it into a new Development directory. Type the following commands to begin the process:

    ~$ cd ~
    ~$ mkdir Development
    ~$ cd Development
    ~/Development$ git clone https://github.com/OSEHRA/VistA.git
  5. Install Vagrant VirtualBox Guest Additions Plugin. With the latest versions of VirtualBox and Vagrant the mounting of the shared folders may fail. By adding a plugin to Vagrant the Virtualbox Guest Additions will be automatically installed when a VM is brought up. To install the plugin perform the following:
    ~$ cd ~
    ~$ Vagrant plugin install vagrant-vbguest
  6. Provision the VistA development environment VM. Since we have a clone of the VistA repository, we now need to provision a new virtual machine using Vagrant. This process is automated and should take about 30 minutes or longer for slower machines to complete.

    NOTE: If you do not want to install the development directories by default (necessary for the ability to re-run the testing or ImportRG.cmake), you must manually edit the Vagrant file located in Scripts/Install/Ubuntu and remove the -e on line 147. It should look like: s.args = "-i " + "#{ENV['instance']}"

    The scripts to provision the VM are located in VistA/Scripts/Install, and the Vagrant file is located in VistA/Scripts/Install/Ubuntu, since we provision an Ubuntu Virtual Machine. Type the following commands to begin the process.

    ~$ cd Development/VistA/Scripts/Install/Ubuntu
    ~/Development/VistA/Scripts/Install/Ubuntu$ Vagrant up 

    There will be lots of console output in green and red text. For advanced users, green text would be from standard out and red text is from standard error. Just because text is in red it doesn't mean that there really is an error. Vagrant will display an error message if there truly is an error. The provisioning process completes when you are able to see the shell prompt again.

  7. Congratulations! You should now have a working copy of OSEHRA VistA running in VirtualBox! If something goes wrong, you can post a message to the OSEHRA Development Tools Discussion Group with the screen output and someone can help from there. Now, to access VistA functionalities using the Roll-and-Scroll user interface (UI) or the CPRS Windows client application, please check out steps below.

Accessing VistA

The VirtualBox VM sets up the RPC broker, a TCPIP socket-based protocol, which is used for data exchange between VistA and clients such as CPRS, Vitals, and other GUIs. The VM also sets up the SSH service to support the terminal-based Roll-and-Scroll UI. The following ports created on VM.

NOTE: If you are using a cloud provider (AWS/EC2, Rackspace) you will have to open the cloud firewall for the following ports before you begin the provisioning process.

  • 9430 - RPC Broker
  • 22/2222 - SSH (2222 is used for the VirtualBox provider)

NOTE: CPRS uses the RPC Broker and the correct command line arguments for VirtualBox are: S=127.0.0.1 P=9430. If you used a cloud provider (Rackspace, AWS) the easiest way to find out what the S= needs to be is to lookup your DNS address in the management portal of your cloud provider.

You can also access the VM using SSH client such as PuTTY by using the address as described in the note above and using the correct port; 22 for cloud installs and 2222 for local VirtualBox installs.

Ubuntu VM User Accounts:

There are two operation systems user accounts that are created automatically during the installation process that make accessing the VistA Roll-and-Scroll UI easier. The use of the accounts becomes clear when you use the Roll-and-Scroll UI in the later section below:

NOTE: by default ${instance} is osehra. The GT.M system runs under the “osehra” system account.

Linux User Name Password
root docker
osehratied tied
osehraprog prog

VistA User Accounts:

User Role Access Code Verify Code Electronic Signature
System Manger SM1234 SM1234!!! n/a
Doctor fakedoc1 1Doc!@#$ ROBA123
Nurse fakenurse1 1Nur!@#$ MARYS123
Clerk fakeclerk1 1Cle!@#$ CLERKJ123

Accessing VistA Using the CPRS, Vitals, BCMA Demo Client Applications, and Terminal

Go to the install clients page

Accessing VistA Using the Roll-and-Scroll UI

The following instruction only provides the steps to login to the OSEHRA VistA instance. To use the Roll-and-Scroll features, please consult FileMan 22.0 Getting Start Manual.

NOTE: Every time a new Vagrant VM is created a new SSH machine key is generated, which has a new fingerprint. Some SSH clients will complain about this and will prevent you from logging on. There are typically instructions in the error message to resolve this connection problem.

  • To login as a doctor, nurse, or clerk, use “osehratied” user account:
~$ ssh -p 2222 osehratied@localhost 

Then type the password “ tied”at the password prompt

The “osehratied” account is designed for regular VistA users to access roll-and-scroll applications. This user is tied to the ^ZU routine.

  • To login as the system manager, use “osehraprog” user account:
~$ ssh -p 2222 osehraprog@localhost 

Then type the password “prog” at the password prompt

The osehraprog is designed for programmer users to access the M prompt. This is the equivalent of typing mumps -dir at the command line.

  • To login as a Linux user (with sudo privileges, password=”vagrant”), type the following commands:
~$ cd Development/VistA/Scripts/Install/Ubuntu 
~/Development/VistA/Scripts/Install/Ubuntu$ Vagrant ssh 

You are now logged in to the VM using the “vagrant” system account. You can now use the system like any other Linux box. If you need to access the VistA environment you can perform the following command:

vagrant@vagrant-ubuntu-precise-32:~$ mumps -dir 

Which will give you a programmer prompt. To get to the normal VistA login screen type the following:

OSEHRA> D ^ZU 

NOTE: the prompt, OSEHRA>, is based on the $instance variable as referenced above.

To access the files on the VM using SFTP, you must connect as the “vagrant” user, password=”vagrant” or the account pre-created if you are using a cloud provider (EC2/Rackspace).

Shutdown Vagrant VM

To exit from the VM session, type

vagrant@vagrant-ubuntu-precise-32:~$ exit 

Or to exit from the VistA session, type

OSEHRA> HALT 

Now that you are back to the host machine, you can:

  • Shut down the VistA VM by typing
~/Development/VistA/Scripts/Install/Ubuntu$ vagrant halt

vagrant halt” will stop the created VM and shutdown the guest operating system. To continue using the created VM in the future, type “Vagrant up”, and it will start the VM again.

Or

  • Suspend the VistA VM by typing
~/Development/VistA/Scripts/Install/Ubuntu$ vagrant suspend

"vagrant suspend" will "pause" the VM - saving the memory and execution state to disk. This is useful when you want to save the state you were working in and return to it quickly. To continue using the suspended VM in the future, type “ vagrant resume”.

Restart Vagrant VM

Open a git-bash prompt - look for git-bash in “All Programs” under the Start Menu (Windows) or a bash shell (Linux or Unix).

Once in git-bash shell, type the following command to change the directory to:

~$ cd Development/VistA/Scripts/Install/Ubuntu

The command to restart the VM differs depending on whether you have "Shut Down" or "Suspend" the VistA VM:

  • Restart from a "shut down" state by typing
~/Development/VistA/Scripts/Install/Ubuntu$ vagrant up

Or

  • Restart from a "suspend" state by typing
~/Development/VistA/Scripts/Install/Ubuntu$ vagrant resume