Difference between revisions of "WorldVistA on Ubuntu"

From VistApedia
Jump to: navigation, search
(Connect with a CPRS client)
(Added a Glossary link to Configuration~)
 
(34 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
''Note: More up-to-date instructions for installing the server <!--->[http://kubuntuguide.info/OpenVistA_EHR may exist]<--->[[Astronaut_VistA#Installation_Instructions|may exist]].''
 +
 
WorldVistA consists of two parts: a database server and a collection of client modules. The server runs in Linux, whereas the clients are generally Windows-based (at this time). The first step is to install the WorldVistA server. It can be installed on the operating system of a stand-alone computer or on the guest operating system of a virtual machine (usually running on the same computer as the client modules).
 
WorldVistA consists of two parts: a database server and a collection of client modules. The server runs in Linux, whereas the clients are generally Windows-based (at this time). The first step is to install the WorldVistA server. It can be installed on the operating system of a stand-alone computer or on the guest operating system of a virtual machine (usually running on the same computer as the client modules).
  
Line 6: Line 8:
  
 
* If you will run the WorldVistA server within a virtual machine, then install the Ubuntu Server edition (virtual machine minimal install) into a virtual machine first. See [[VirtualAstronaut|these instructions]].
 
* If you will run the WorldVistA server within a virtual machine, then install the Ubuntu Server edition (virtual machine minimal install) into a virtual machine first. See [[VirtualAstronaut|these instructions]].
 
+
Record
 
Then proceed in a similar fashion (in each type of operating system installation) for the subsequent installation of Astronaut VistA.  
 
Then proceed in a similar fashion (in each type of operating system installation) for the subsequent installation of Astronaut VistA.  
  
Line 12: Line 14:
 
*The Astronaut installer uses an emerging standardized installation framework for VistA derivatives (WorldVistA and OpenVistA currently). These instruction reflect this framework, with modifications I have used in setting up my system on Ubuntu.
 
*The Astronaut installer uses an emerging standardized installation framework for VistA derivatives (WorldVistA and OpenVistA currently). These instruction reflect this framework, with modifications I have used in setting up my system on Ubuntu.
  
*Port 9260 is used for communications with the VistA server. The server should have a [http://ubuntuguide.org/wiki/Ubuntu:All#Set_a_static_IP_address static IP address] on your LAN, and your LAN should forward port 9260 traffic to the VistA server's IP address. Make sure your firewall allows port 9260 traffic.
+
* A secure SSH tunnel is created between the Astronaut client(s) and the Astronaut VistA server using port 22. Information coming from a client's port 9260 is sent through this tunnel and received by the the VistA server's port 9260. (The network only sees traffic over port 22.) So that the network can always find the VistA server, it should have a [http://ubuntuguide.org/wiki/Ubuntu:All#Set_a_static_IP_address static IP address] on the LAN. Your LAN (router) should then forward port 22 (and perhaps port 9260 during testing) traffic to the VistA server's IP address on the LAN. Make sure any firewall running on the VistA server firewall allows port 22 (and, to be safe, port 9260) traffic through.
  
 
It is easiest to set this up before using the Astronaut installer, since the Astronaut server installer autodetects IP address settings.
 
It is easiest to set this up before using the Astronaut installer, since the Astronaut server installer autodetects IP address settings.
  
 
===Installation===
 
===Installation===
[http://worldvista.org WorldVistA] is the largest and most robust CCHIT-approved electronic health record platform in the public domain. It is is based on the US Veterans Administration health record system and is GPL licensed. The database and server can be installed on a standalone server (which would then be accessed over a network by clients on other computers) or can be installed in a [[VirtualAstronaut|virtual machine]] on a computer which also contains the [[#Connect_with_a_CPRS_client|clients]] (creating a self-contained EHR on a single computer). There are several installation packages. The original WorldVistA site is [http://worldvista.org/Software_Download/worldvista-ehr-auto-installers here].
+
[http://worldvista.org WorldVistA] is the largest and most robust CCHIT-approved electronic health [[record~|Record]] platform in the public domain. It is is based on the US Veterans Administration health [[record~|Record]] system and is GPL licensed. The database and server can be installed on a standalone server (which would then be accessed over a network by clients on other computers) or can be installed in a [[VirtualAstronaut|virtual machine]] on a computer which also contains the [[#Connect_with_a_CPRS_client|clients]] (creating a self-contained EHR on a single computer). There are several installation packages. (The original WorldVistA site is [http://worldvista.org/Software_Download/worldvista-ehr-auto-installers here].)
  
*Apache2 is required. It can be installed individually (sudo apt-get install apache2) or as part of a [http://ubuntuguide.org/wiki/Ubuntu:All#LAMP_server_installation LAMP] (Linux, Apache2, MySQL5, PHP) installation:
+
*Apache2 is required. It can be installed individually (sudo apt-get install apache2) or as part of a [http://ubuntuguide.org/wiki/Ubuntu:All#LAMP_server_installation LAMP] (Linux, Apache2, MySQL, PHP) installation:
 
  sudo tasksel install lamp-server
 
  sudo tasksel install lamp-server
  
Line 28: Line 30:
 
  sudo apt-get install wget iptables nano
 
  sudo apt-get install wget iptables nano
  
*A beta .deb package called Astronaut WorldVistA EHR (for clinics) is [http://sourceforge.net/projects/worldvistaautoi/files/ available here]. See [http://astronautvista.com/ the Astronaut website] for additional installation instructions.
+
*A package can be installed directly from the Astronaut VistA repositories (replace ''lucid'' with ''karmic'' if using Karmic Koala 9.10) by adding the repository:
 +
sudo echo "deb <nowiki>http://software.astronautvista.com/deb</nowiki> ''lucid'' main" >> /etc/apt/sources.list.d/lucid-partner.list
 +
sudo apt-get update
 +
 
 +
::then installing the Astronaut version of the OpenVistA server:
 +
sudo apt-get install astronaut-wv-server-beta
 +
<!--->
 +
*A beta .deb package called Astronaut WorldVistA EHR (for clinics) is [http://sourceforge.net/projects/worldvistaautoi/files/ available here]. (See [http://astronautvista.com/ the Astronaut website] for additional installation instructions.)
 
:*Install prerequisites:
 
:*Install prerequisites:
 
  sudo apt-get install xinetd update-inetd whois apache2-suexec
 
  sudo apt-get install xinetd update-inetd whois apache2-suexec
Line 34: Line 43:
 
  sudo apt-get ia32-libs
 
  sudo apt-get ia32-libs
 
:*Obtain and install Astronaut WorldVistA:
 
:*Obtain and install Astronaut WorldVistA:
  wget -O astronaut-wv-server-current.deb <nowiki>http://downloads.sourceforge.net/project/worldvistaautoi/Astronaut%20WorldVistA%20Server%20Installers/astronaut-wv-server-beta-0.9-3.deb?use_mirror=superb-sea2</nowiki>
+
  wget -O astronaut-wv-server-current.deb <nowiki>http://sourceforge.net/projects/worldvistaautoi/files/Astronaut%20WorldVistA%20Server%20Installers/astronaut-wv-server-beta-0.9-3.deb/download</nowiki>
 
  sudo dpkg -i astronaut-wv-server-current.deb
 
  sudo dpkg -i astronaut-wv-server-current.deb
 
+
<--->
 +
<!--->
 
Note: It is recommended to install WorldVistA on a dedicated server. Apache and other server settings will be altered by the installation, which may alter your ability to run other servers on the same machine.
 
Note: It is recommended to install WorldVistA on a dedicated server. Apache and other server settings will be altered by the installation, which may alter your ability to run other servers on the same machine.
 +
>--->
 +
*Open incoming ports 9260 and 22 in your [http://ubuntuguide.org/wiki/Ubuntu:All#Firewall firewall]. If behind a router, make sure these ports are forwarded to the IP address of the computer acting as the WorldVistA server.
  
*Open incoming port 9260 in your [http://ubuntuguide.org/wiki/Ubuntu:All#Firewall firewall]. If behind a router, make sure this port is forwarded to the IP address of the computer acting as the WorldVistA server.
+
*Note: Astronaut routes all communications through an SSH tunnel (port 22) using PuTTY (on the client side) and OpenSSH (on the server side). If you will only connect using this SSH tunnel, you do not need port 9260 to be open on (or forwarded by) your router. Alternatively, if you connect between clients and the server directly (using port 9260), then you do not need port 22 to be open. Note that connecting directly through port 9260 directly is slightly less secure, so it is discouraged when connecting through the Internet.
 
 
*Note: This installation installs the WorldVistA database and server in an Ubuntu Linux OS (that resides either on a standalone computer or in a [[VirtualAstronaut|virtual machine]]). The [[#Connect_with_a_CPRS_client|CPRS user client]] for WorldVistA is written in Delphi for Windows (and works imperfectly in Wine). The CPRS client is therefore usually installed onto a Windows-based PCs (or onto USB flashdrives). These CPRS clients connect through the network to the WorldVistA server on a Ubuntu Linux-based server PC, or directly to the virtual machine.
 
  
 +
*Note: This installation installs the WorldVistA database and server in an Ubuntu Linux OS (that resides either on a standalone computer or in a [[VirtualAstronaut|virtual machine]]). The [[#Connect_with_a_CPRS_client|CPRS user client]] for WorldVistA is written in Delphi for Windows (and works imperfectly in Wine). The CPRS client is therefore usually installed onto a Windows-based PCs (or onto USB flashdrives). These CPRS clients connect through the network to the WorldVistA server on a Ubuntu Linux-based server PC, or directly to the server running in a virtual machine.
 +
<!--->
 
*Also see the [http://www.youtube.com/watch?v=4So0ulz0XVk Astronaut installation YouTube video] and the [http://www.youtube.com/watch?v=xzTJw8axJds Astronaut Client Server Manager YouTube video].
 
*Also see the [http://www.youtube.com/watch?v=4So0ulz0XVk Astronaut installation YouTube video] and the [http://www.youtube.com/watch?v=xzTJw8axJds Astronaut Client Server Manager YouTube video].
 +
<--->
  
 
===Installation Notes===
 
===Installation Notes===
Line 53: Line 66:
 
*The listener port for m2web is 80.
 
*The listener port for m2web is 80.
  
The following default actions where done:
+
The following default actions were done:
  
 
  gtm Mumps interpreter installed in: /opt/lsb-gtm/gtm
 
  gtm Mumps interpreter installed in: /opt/lsb-gtm/gtm
Line 72: Line 85:
 
  Port: 9260
 
  Port: 9260
  
(Obviously, use the IP address of your own server.)
+
(Obviously, [[record~|Record]] the IP address of your own server.)
  
 
=== Installing on a Server edition ===
 
=== Installing on a Server edition ===
If you are installing on a Server edition without a desktop/package manager installed, you may need to install as root:
+
<!--->If you are installing on a Server edition without a desktop/package manager installed, you may need to install as root:
 
  sudo -s
 
  sudo -s
 
  sudo dpkg -i astronaut-wv-server-current.deb
 
  sudo dpkg -i astronaut-wv-server-current.deb
 
  sudo apt-get -f install
 
  sudo apt-get -f install
 
+
<--->
 
Note: The command "apt-get -f install" finds and installs unmet dependencies. This is only needed for Server editions in which a package manager is not installed.
 
Note: The command "apt-get -f install" finds and installs unmet dependencies. This is only needed for Server editions in which a package manager is not installed.
  
Line 96: Line 109:
 
The network administrator must assign the static IP address on the LAN for use by the server (especially if a DNS nameserver is in use on the network). Let's say the LAN has a router/gateway address of 192.168.1.1, a static IP address range of 192.168.1.125 - 192.168.1.253, and the server is assigned an IP address of 192.168.1.135. Then the Ubuntu Server can be configured to use this static IP address.
 
The network administrator must assign the static IP address on the LAN for use by the server (especially if a DNS nameserver is in use on the network). Let's say the LAN has a router/gateway address of 192.168.1.1, a static IP address range of 192.168.1.125 - 192.168.1.253, and the server is assigned an IP address of 192.168.1.135. Then the Ubuntu Server can be configured to use this static IP address.
  
*When the Ubuntu Server OS is running, edit the /etc/network/interfaces configuration file:
+
*When the Ubuntu Server OS is running, edit the /etc/network/interfaces [[configuration~|Configuration]] file:
 
  sudo nano /etc/network/interfaces
 
  sudo nano /etc/network/interfaces
  
Line 119: Line 132:
 
=== Connect with a CPRS client ===
 
=== Connect with a CPRS client ===
  
*See the [[Astronaut CPRS client package]] instructions.
+
*See the [[Astronaut CPRS client package]] installation and [[configuration~|Configuration]] instructions.
* Download the [http://sourceforge.net/projects/worldvistaautoi/files/ Astronaut CPRS client] onto your Windows machine and install it. During installation, enter the IP address (or hostname URL) and port (9260 by default) of the server you installed in the preceding steps.
 
* The SSH tunneling utility PuTTY is installed with the CPRS client. It will start automatically on the first run. Do not close PuTTY; merely minimize it (to the desktop taskbar).
 
* Start the CPRS client:
 
:Windows menu -> All Programs -> Astronaut -> TMG-CPRS
 
* Use the default login intially:
 
Access Code: ''sys.admin''
 
Verify Code: ''vista!123''
 
 
 
You can watch a YouTube video of TMG-CPRS [http://www.youtube.com/watch?v=ojcIoIy7HC4 here].
 
 
 
When done with your CPRS session, you can close the PuTTY SSH tunnel. Subsequently, however, you must restart the PuTTY SSH tunnel (and then minimize it) prior to making a new CPRS (or other) connection:
 
:Windows menu -> All Programs -> Astronaut -> Astronaut SSH
 
 
 
You can then restart CPRS again:
 
:Windows menu -> All Programs -> Astronaut -> TMG-CPRS
 
 
 
There are several settings in the Astronaut Client package that can be changed. For more details on installing and changing this package to suit your installation, see [[Astronaut CPRS client package|this Astronaut Client Package]] page.
 
 
 
=== Using the VistA Configuration Utility ===
 
The Astronaut WorldVistA package comes pre-populated with sample users, patients, and settings. You can add additional users and patients and change settings using the VistA Config utility. (Make sure the PuTTY SSH tunnel is open before using it.) [http://www.youtube.com/watch?v=6ElaN6uTbYw Here] is a YouTube video that is a good introduction to this utility.
 
 
 
:Windows menu -> All Programs -> Astronaut -> VistA Config
 
 
 
* Add a new physician user:
 
:VistA Config -> Users -> Active Users -> DOCTOR,TWO -> Clone User
 
 
 
this will create a new user in the Inactive Users section named TEMP,MUST-EDIT. Click on the user to edit it:
 
:VistA Config -> Users -> Inactive Users -> TEMP,MUST-EDIT
 
 
 
Edit the fields. For example:
 
:* NAME: ''SCHWEITZER,ALBERT''
 
:* INITIAL: ''AS''
 
:* ACCESS CODE: ''ASCHWEITZER''
 
:* VERIFY CODE: ''ASVERIFYCODE''
 
:* DISUSER: NO
 
:* ELECTRONIC SIGNATURE CODE: ''ASSIGCODE''
 
:* PRIMARY MENU OPTION: DGZ REGISTRATION MENU
 
  
:The field DISUSER: stands for disabled user. When it is set to YES, the user remains in the Inactive Users section (i.e. disabled). When it is set to NO, the user is moved to the Active Users section (i.e. enabled). When all the fields have been set as desired, click Apply.
+
=== Using the VistA [[Configuration~|Configuration]] Utility ===
  
Now this user can log in using CPRS (or other utility), with the Access Code and Verify code that has been assigned.
+
*See the [[VistA Configuration Utility]] usage instructions.
  
 
=== Using the VistA Clinical Scheduling utility ===
 
=== Using the VistA Clinical Scheduling utility ===
The VistA Clinical Scheduling utility may advertise itself (at startup) as using port 10501, but it has been altered to use port 9260 (just like the other Astronaut client modules).
+
The Clinical Scheduler from the Indian Health System's RPMS system has been imported as one of the modules included with an Astronaut VistA installation.  
 
+
* After starting, if an "Unable to connect to VistA" error appears, then click the "Retry" button. A configuration screen will appear. Enter:
+
*See the [[VistA Clinical Scheduling Utility]] usage instructions.
:RPMS server address: ''192.168.56.101''
 
:Server Port: 9260
 
 
 
Use the IP address of your VistA server in place of the RPMS server address (use your own VistA server IP address, obviously). Always use Server Port 9260 (''not'' 10501).
 
 
 
* When prompted for the RPMS Access Code and RPMS Verify Code, use the VistA Access Code and VistA Verify Code established for your user (e.g. ''sys.admin'' / ''vista!123'' for the initial administrator, as above).
 
 
 
=== Configure access to the WorldVistA server from the Internet through a virtual server ===
 
(This section is under construction.)
 
 
 
*Copy and edit a configuration file in the Apache2 sites-available folder.
 
cd /etc/apache2/sites-available
 
sudo cp default worldvista
 
sudo kate worldvista
 
  
*Edit the virtual host file so that it looks like:
+
=== Configure access to the VistA server from the Internet through a virtual server ===
<VirtualHost *:9260>
 
ServerAdmin webmaster@''worldvista.myoffice.org''
 
DocumentRoot /opt/worldvista/EHR
 
ServerName ''worldvista.myoffice.org''
 
ServerAlias www.''worldvista.myoffice.org'' ''worldvista.myoffice.org''
 
</VirtualHost>
 
  
where ''worldvista.myoffice.org'' is an example URL for your server (use your own, of course)
+
*See [[Ubuntu Virtual Servers]]
  
*Restart Apache2:
+
== Other resources ==
sudo /etc/init.d/apache2 restart
+
*This page was adapted from [http://kubuntuguide.info/WorldVistA_EHR Kubuntuguide].

Latest revision as of 05:58, 4 December 2012

Note: More up-to-date instructions for installing the server may exist.

WorldVistA consists of two parts: a database server and a collection of client modules. The server runs in Linux, whereas the clients are generally Windows-based (at this time). The first step is to install the WorldVistA server. It can be installed on the operating system of a stand-alone computer or on the guest operating system of a virtual machine (usually running on the same computer as the client modules).

When the VistA server is run within a virtual machine on the same computer as the client modules, a fully self-contained WorldVistA EHR is created on a single computer.

  • If you will run the WorldVistA server within a virtual machine, then install the Ubuntu Server edition (virtual machine minimal install) into a virtual machine first. See these instructions.

Record Then proceed in a similar fashion (in each type of operating system installation) for the subsequent installation of Astronaut VistA.

Preparing your server

  • The Astronaut installer uses an emerging standardized installation framework for VistA derivatives (WorldVistA and OpenVistA currently). These instruction reflect this framework, with modifications I have used in setting up my system on Ubuntu.
  • A secure SSH tunnel is created between the Astronaut client(s) and the Astronaut VistA server using port 22. Information coming from a client's port 9260 is sent through this tunnel and received by the the VistA server's port 9260. (The network only sees traffic over port 22.) So that the network can always find the VistA server, it should have a static IP address on the LAN. Your LAN (router) should then forward port 22 (and perhaps port 9260 during testing) traffic to the VistA server's IP address on the LAN. Make sure any firewall running on the VistA server firewall allows port 22 (and, to be safe, port 9260) traffic through.

It is easiest to set this up before using the Astronaut installer, since the Astronaut server installer autodetects IP address settings.

Installation

WorldVistA is the largest and most robust CCHIT-approved electronic health Record platform in the public domain. It is is based on the US Veterans Administration health Record system and is GPL licensed. The database and server can be installed on a standalone server (which would then be accessed over a network by clients on other computers) or can be installed in a virtual machine on a computer which also contains the clients (creating a self-contained EHR on a single computer). There are several installation packages. (The original WorldVistA site is here.)

  • Apache2 is required. It can be installed individually (sudo apt-get install apache2) or as part of a LAMP (Linux, Apache2, MySQL, PHP) installation:
sudo tasksel install lamp-server
sudo tasksel install openssh-server
  • If you are installing on a Server edition without a desktop, you will also need:
sudo apt-get install wget iptables nano
  • A package can be installed directly from the Astronaut VistA repositories (replace lucid with karmic if using Karmic Koala 9.10) by adding the repository:
sudo echo "deb http://software.astronautvista.com/deb lucid main" >> /etc/apt/sources.list.d/lucid-partner.list
sudo apt-get update
then installing the Astronaut version of the OpenVistA server:
sudo apt-get install astronaut-wv-server-beta
  • Open incoming ports 9260 and 22 in your firewall. If behind a router, make sure these ports are forwarded to the IP address of the computer acting as the WorldVistA server.
  • Note: Astronaut routes all communications through an SSH tunnel (port 22) using PuTTY (on the client side) and OpenSSH (on the server side). If you will only connect using this SSH tunnel, you do not need port 9260 to be open on (or forwarded by) your router. Alternatively, if you connect between clients and the server directly (using port 9260), then you do not need port 22 to be open. Note that connecting directly through port 9260 directly is slightly less secure, so it is discouraged when connecting through the Internet.
  • Note: This installation installs the WorldVistA database and server in an Ubuntu Linux OS (that resides either on a standalone computer or in a virtual machine). The CPRS user client for WorldVistA is written in Delphi for Windows (and works imperfectly in Wine). The CPRS client is therefore usually installed onto a Windows-based PCs (or onto USB flashdrives). These CPRS clients connect through the network to the WorldVistA server on a Ubuntu Linux-based server PC, or directly to the server running in a virtual machine.

Installation Notes

  • The MUMPS database (GT.M) is installed into /opt/lsb-gtm/V5.3-004A_i686.
  • The WorldVistA EHR program is installed into /opt/worldvista/EHR.
  • m2web is installed into /opt/worldvista/EHR/web/m2web.
  • A startup file is installed as /etc/init.d/vista-EHR.
  • The listener port for clients like CPRS is 9260.
  • The listener port for m2web is 80.

The following default actions were done:

gtm Mumps interpreter installed in: /opt/lsb-gtm/gtm
Default user id created: worldvistaEHR in /home/worldvistaEHR
textEHR user id created.
VistA software installed in: /opt/worldvista/EHR
Started port listener on port: 9260
Open port: 9260

NEXT STEPS: Log in as user: worldvistaEHR with default password: vista!123 You will be prompted to immediately change the password. Use a strong password. Full disk encryption of your Linux is strongly recommended.

Write down the IP address of this machine and port:

IP address of this machine:
192.168.0.24
Port: 9260

(Obviously, Record the IP address of your own server.)

Installing on a Server edition

Note: The command "apt-get -f install" finds and installs unmet dependencies. This is only needed for Server editions in which a package manager is not installed.

Installing WorldVistA Server in a Virtual Machine

There are two methods for doing this.

  • Install the Ubuntu Server edition (virtual machine minimal install) into a virtual machine (like VirtualBox) and then install Astronaut WorldVistA on top of this. See these instructions.
  • The WorldVistA EHR Personal Toaster is a self-contained appliance for Windows that includes a bundled QEMU virtual machine, a Damn Small Linux operating system, and a WorldVistA server (it does not use the Astronaut format). All are installed in a one-step process.

Another example solution is demonstrated in this YouTube video.

Use a static IP address for the server

It will be difficult for the WorldVistA clients to locate the WorldVistA server if the IP address of the server is always changing (i.e. repeatedly assigned a new dynamic IP address by the router/network DHCP server). It is best, therefore, to assign a static IP adress to the server.

The network administrator must assign the static IP address on the LAN for use by the server (especially if a DNS nameserver is in use on the network). Let's say the LAN has a router/gateway address of 192.168.1.1, a static IP address range of 192.168.1.125 - 192.168.1.253, and the server is assigned an IP address of 192.168.1.135. Then the Ubuntu Server can be configured to use this static IP address.

  • When the Ubuntu Server OS is running, edit the /etc/network/interfaces Configuration file:
sudo nano /etc/network/interfaces
  • Make sure the settings are similar to:
# The loopback network interface
auto lo
iface lo inet loopback
#
# The primary network interface
auto eth0
#iface eth0 inet dhcp
#
iface eth0 inet static
address 192.168.1.135
broadcast 192.168.1.255
netmask 255.255.255.0
gateway 192.168.1.1
  • Reboot the Ubuntu OS again so that the new IP address is used.
sudo reboot

Connect with a CPRS client

Using the VistA Configuration Utility

Using the VistA Clinical Scheduling utility

The Clinical Scheduler from the Indian Health System's RPMS system has been imported as one of the modules included with an Astronaut VistA installation.

Configure access to the VistA server from the Internet through a virtual server

Other resources