Difference between revisions of "WorldVistA Server in VirtualBox"

Latest revision as of 19:08, 19 December 2012

VirtualBox (by Sun) has a free proprietary edition as well as a subscription-based enterprise edition. The free edition only allows the usage of a 32-bit operating system (as the guest OS) whereas the subscription edition allows a 64-bit guest OS. (There is a free open source edition, but installing it in Windows is not very easy (unlike in Linux).) It is possible to convert virtual machines created in VirtualBox to VMWare and vice versa.

I found both the installation process and the interface for VirtualBox very user-friendly, so it is my preferred solution for stand-alone systems and for smaller networks.

Install Virtualbox in Windows

(During the entire installation process I recommend turning off your firewall. Once everything is working properly, turn your firewall back on and then adjust it so that everything again functions properly. VirtualBox has a somewhat complex networking structure that is sure to bamboozle even the most sophisticated firewall. I spent more than half my installation time working with the firewall.)

• See installing VirtualBox in Windows.

Install Ubuntu server in a virtual machine

There is a version of the Ubuntu server that is optimised for usage within a virtual machine. It is provided on the Ubuntu Server edition LiveCD. The LiveCD image (.iso) found here can be downloaded onto your hard drive. It can then be installed into your virtual machine directly from the hard drive. Alternatively, you can also burn the .iso image onto a CD and install Ubuntu Server into the virtual machine from the CD. Both methods work identically during the Ubuntu Server installation process.

The free version of VirtualBox only allows the use of a 32-bit operating system as a guest OS, so you should download the 32-bit Ubuntu server (.iso) image.

• Start the virtual machine you created in the previous step.

Virtualbox -> UbuntuVirtualServer (highlighted) -> Start

The "Welcome to the First Run Wizard" will Prompt for the location of the installation disk -> Next ->

CD/DVD-ROM device (ticked) ->

Media Source:

• select the CD-ROM drive (if you burned the LiveCD (.iso) image onto a physical CD), or
• browse (click on the folder icon) for the folder where you stored the (.iso) image onto your hard drive (if you did not burn it to a physical CD)

• -> Add... -> choose the location where you saved the (.iso) image -> Select

-> Next -> Finish

• Install Ubuntu server virtual machine edition:

The First Run Wizard will automatically start the LiveCD from the location you indicated, and you will see the Ubuntu Server LiveCD screen.

• Choose language: English ->
• Important: note this step carefully! Select the minimal virtual machine installation mode:

* Click the F4 (modes) key -> Install a minimal virtual machine ->

• Install Ubuntu Server

• Select your installation options. When asked about partitioning, use the guided partitioning method and use the entire disk. This uses the entire virtual machine disk (which is 8 GB or whatever size you created when creating the virtual machine), not the entire physical hard drive disk.

• Task selection. A menu will appear to select options for additional packages to be installed along with the server. Now is a good time to install two packages that will be required by WorldVistA: the LAMP (Linux, Apache2, MySQL, and PHP) server package, and the OpenSSH package. Make sure these two packages are starred (use the space button to select them) before completing the installation.

• You will be prompted to enter an MySQL root user password during the LAMP server package installation. This password becomes important later on (in some instances). Record your chosen MySQL password in a safe location. Do not use your primary user password as the MySQL password; it ought to be unique.

• Finish the remainder of the Ubuntu Server installation. At the conclusion the Ubuntu system will automatically reboot within the virtual machine. When it restarts, you will then have a fully function Ubuntu Server within the virtual machine. Login using the primary user and password (that you created during the Ubuntu Server installation process) and immediately update the operating system:

sudo apt-get update
sudo apt-get upgrade

• If you added the Ubuntu Server edition (.iso) CD image (stored on your hard drive) as a bootup storage device for the virtual machine, you must remember to remove it (once installation has been completed). (This is only necessary if you used the (.iso) image on your hard drive to install the Ubuntu Server.)

• Stop the Ubuntu Server OS (sudo halt) and shutdown (close) the virtual machine.
• VirtualBox -> Machine -> Settings -> Storage -> ubuntu-9.10-server-i386.iso -> Remove attachment (-) icon (looks like a computer drive symbol with a (-) sign on it) -> Remove -> OK

Install a desktop

This is a decision that is difficult to make. Having an Ubuntu or Kubuntu GUI desktop is nice, but it also slows down the virtual machine server considerably and takes a large chunk of the 8.00 GB virtual disk (which may need to be dynamically expanded and thereby occupy more space on your hard-drive). A GUI desktop is not required to run the WorldVistA server.

If you intend to use many other features of Ubuntu or Kubuntu, however, this may be worthwhile. To install a desktop:

sudo apt-get install ubuntu-desktop

or

sudo apt-get install kubuntu-desktop

• After all the packages are installed, restart the OS within the virtual machine (sudo reboot) and you should now boot into the GUI desktop.

Install pre-requisites if no desktop installed

To run the WorldVistA server, a GUI desktop is not required. (Personally, I don't use a desktop for the virtual machine server.) But to do this, several packages that are normally installed with the desktop must be installed individually:

• Install wget (to retrieve packages) and iptables (for firewall rules) and nano (for Configuration file editing):

sudo apt-get install wget iptables nano

• Also install some packages that the WorldVistA server requires:

sudo apt-get install whois xinetd update-inetd apache2-suexec

Download the Astronaut WorldVistA server package

Depending on the networking Configuration selected in the next step, Internet access for the virtual machine may not be available (if the "host-only adapter" networking mode is selected, for example). Therefore, it is important to download all packages from the Internet prior to changing the network adapter Configuration.

• Download (but do not install) the Astronaut WorldVistA server package:

wget -O astronaut-wv-server-current.deb http://downloads.sourceforge.net/project/worldvistaautoi/Astronaut%20WorldVistA%20Server%20Installers/astronaut-wv-server-beta-0.9-3.deb?use_mirror=superb-sea2

The Astronaut installer recognizes the network Configuration during installation, so Astronaut installation should not be started until the virtual machine's network adapter is configured correctly (see below).

• If the virtual machine cannot connect to the Internet, you must restore a network-adapter Configuration that allows it. Use either the NAT Adapter mode or the Bridged Adapter mode. Shutdown the Ubuntu Server OS (sudo halt) and close the virtual machine before changing the network adapter mode. Restart the virtual machine after changing the mode.

Configure virtual machine networking

• (During the entire installation process I recommend turning off your firewall. Once everything is working properly, turn your firewall back on and then adjust it so that everything again functions properly. VirtualBox has a very complex networking structure that is sure to bamboozle even the most sophisticated firewall. I spent more than half my installation time working with the firewall.)

• This can be a tricky exercise, depending on your intent. For VirtualBox networking options, read the Help Manual provided within the VirtualBox console:

VirtualBox -> Help -> Contents -> Virtual Networking

The Ubuntu Server OS should be shutdown (sudo halt) and the virtual machine stopped (closed) whenever networking changes are made. The Ubuntu Server OS will then recognize the changes when it is restarted (rebooted).

Bridged Adapter

The Bridged Adapter is the most flexible mode and is therefore recommended for initial setup. Using this mode, both the clients on the host computer as well as clients on the LAN will be able to access the server in the virtual machine.

VirtualBox -> Machine -> Settings -> Network ->

Enable Network Adapter: (ticked)

Attached to: Bridged Adapter

Name: Atheros AR5009 802.11 a/g/n WiFi Adapter

Advanced -> Adapter Type: PCnet-Fast III

Cable connected: (ticked)

Obviously, use the name of whichever adapter your computer uses to connect to the network. (Mine happens to connect wirelessly with an Atheros AR5009 wireless adapter.) The virtual Advanced Adapter Type (PCnet-Fast III) is a default adapter type that should almost always work. The virtual machine will obtain an IP address from the DHCP-assigned pool on your LAN.

Setting a static IP address for the virtual machine server

It is often desirable to have a static IP address on the LAN for your virtual machine server. The network administrator must assign the static IP address on the LAN for use by the virtual 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 virtual server is assigned an IP address of 192.168.1.135. Then the Ubuntu Server guest OS (in the virtual machine) can be configured to use this static IP address.

• Once the virtual machine is again running and the Ubuntu Server OS re-started, 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

Host-only Adapter

• For a self-contained single-computer EHR, the VirtualBox "Host-only Adapter" mode can be useful. The virtual machine will create an IP address (from its own unique IP address pool). In this mode the Windows host operating system (which has the WorldVistA client modules) communicates directly with the Ubuntu Linux guest operating system running in the virtual machine (where the WorldVistA server resides). The SSH connection established by the Astronaut installer will then connect directly (through an internal "loopback" arrangement). No other computer on the LAN will be able to access the server in the virtual machine using this mode, however.

VirtualBox -> Machine -> Settings -> Network ->

Enable Network Adapter (ticked)

Attached to: Host-only Adapter

Name: VirtualBox Host-Only Ethernet Adapter

NAT Adapter

This mode is a simplified networking mode in which the virtual machine obtains a DHCP-assigned temporary address from the LAN. The virtual machine cannot act as a server using this mode, but can still connect to the Internet (through the host adapter). This mode is useful for temporarily connecting to the Internet (to accomplish software updates for the guest OS, for example), since this cannot be done in Host-only adapter mode. This mode should not be enabled during the installation of the Astronaut WorldVistA server (use one of the other two modes instead).

If I have any trouble with the Ubuntu Server installation in Bridged networking mode, I use this NAT networking mode instead. Once the Ubuntu Server is fully installed and functioning, then I change VirtualBox to Bridged (or Host-only) Networking mode for installation of the VistA server.

Check the IP address of the virtual machine

When using the Bridged and Host-only Adapter modes, an IP address for the virtual machine will be generated. It is important to make sure that this IP address can then be reached from the host operating system. (If not, the problem most often resides with the firewall, or with the adapter-bridging Configuration, or perhaps even with the LAN's router/DHCP server.)

• Start the Ubuntu virtual machine and from a command-line terminal examine the IP address:

ifconfig

• For a Bridged Adapter mode, the eth0 networking interface should read something like 192.168.1.119 (or some other number obtained from the DHCP-assigned IP address pool of your LAN).
• For a Host-only Adapter mode, the eth0 networking interface should read something like 192.168.56.101. (This is an ersatz IP address that the virtual machine will create and present (as its own) to the host OS.)

Whichever IP address is reported here will be the one that the WorldVistA server automatically detects during installation and will subsequently use. It therefore should also be used for the clients.

If you change adapter modes (followed by a reboot of the Ubuntu OS within the virtual machine), the WorldVistA server will correctly recognize the change and use whichever new IP address is generated. However, you must again check the IP address (using ifconfig) and then change the ASTRO_SSH_CLIENT environment variable (in the host OS) so that it is the same as the current virtual machine IP address. This is needed in order for the PuTTY SSH connection to be properly established.

• To be sure that the Windows host can connect to the Ubuntu guest OS (in the virtual machine), open a Windows command Prompt:

Windows Start menu -> Programs -> Accessories -> System Tools -> Command Prompt ->

ping 192.168.1.119

or

ping 192.168.56.101

If you get a response, then the internal networking connection is working properly.

Install the WorldVistA server into the virtual machine

• Use the Astronaut VistA installer to install the WorldVistA server (downloaded in a previous step) into the Ubuntu Server OS running in the virtual machine:

sudo dpkg -i astronaut-wv-server-current.deb

• The installer will automatically recognize the IP address of the VirtualBox virtual machine to be 192.168.56.101, as well as Instance Name: EHR and Port: 9260.

• The initial login ID is noted to be worldvistaEHR with an initial default password vista!123. This is used for logging into the WorldVistA server directly from within the Ubuntu Server OS. It is not the access code/verify code pair that a user enters when logging in from a WorldVistA client module (e.g. TMG-CPRS).

Install the Astronaut WorldVistA Clients on the host OS

• See Connecting with a CPRS client.

• When installing the Astronaut clients, use the IP address of the virtual machine (192.168.56.101, for example) as the server address.