Skip to content Skip to navigation

Installation Documentation

Installation Overview

ePAD is distributed as a standalone virtual machine (VM) or a set of four Docker images. Go to the Download link to get an ePAD server VM image or the Docker installation script. The images provides a fully functional ePAD installation.

This page describes both how to set up an ePAD VM to run locally on a laptop or desktop computer and how to set it up as a network-accessible VM.

Installing on Laptop or Desktop using the VMWare Image

You will need administrator privileges on the host machine to perform many of the steps outlined in these instructions. On OS X you must first install VMware Fusion. On Windows or Linux-based hosts, VMware Workstation or VMWare Player (free download) is required.

The ePAD VM image that you will receive from us will be in a ZIP called epad-vm.zip. Unzip this file. Unzipping will create a directory called epad-vm. The first step is to load the virtual machine into VMware. To do this, select the menu item File->Open and select this directory or file epad-vm.vmx. VMware will then load the image (which may take a while). After loading it may ask you if the file was copied or moved. If so, select copied. The created VM will have the name epad-vm. (This is the name VMware uses for the VM. It is not necessarily the same as the host name of the VM.) The VM is running the CentOS operating system.

After loading you should be able to start the VM. However, before running ePAD some configuration steps are necessary. The first configuration step is to ensure that the ePAD virtual machine uses the same IP address every time it starts and to map this IP address to the host name epad-vm.

The default configuration for the ePAD VM is 'host only' mode. This mode means that the virtual machine is only visible from the host machine and cannot be reached from other machines. To specify host only mode in VMware, select Virtual Machine->Network Adapter->Host Only. (It may already have this mode selected.)

The next step is to start the ePAD virtual machine to retrieve some settings from it. In VMware, select Virtual Machine->Start Up and start the epad-vm virtual machine. When the ePAD virtual machine has started, log on as user epad using the password epad. You will first need to start up a terminal in the CentOS VM by selecting Applications->System Tools->Terminal. On the command line then type ifconfig. You should see something like the following:

eth0 Link encap:Ethernet HWaddr 00:0C:29:6D:42:4D
inet addr:172.16.112.100 Bcast:172.16.112.255 Mask:255.255.255.0
...

The information after HWaddr on the first line (00:0C:29:6D:42:4D in this case) is the MAC address of the primary ethernet card on the virtual machine. We will need this address to configure the VM on our machine. Write it down carefully and then shut down the virtual machine (via Virtual Machine->Shutdown in VMware).

We are now going to use this information to configure the VM to use the same IP address every time it boots and to map the host name epad-vm to the machine.

These steps vary by host operating system. We describe the steps needed on OS X and other Unix-based systems and also on Windows systems.

You must first edit VMware's DHCP configuration file. VMware uses DHCP to allocate IP addresses to its virtual machines. On OS X for host-only mode this file is called /Library/Preferences/VMware Fusion/vmnet1/dhcpd.conf. On Linux this file is typically /etc/vmware/vmnet1/dhcp/dhcp.conf. On Windows XP it is C:\Documents and Settings\All Users\Application Data\VMware\vmnetdhcp.conf and on Windows 7 it is C:\ProgramData\VMware\vmnetdhcp.conf.

On OS X and Unix-based systems you can edit the file directly.

On Windows systems using VMware Workstation you can change these DHCP settings by using the VMware Virtual Network Editor tool. If you are using VMware Player you will need to manually edit the DHCP server configuration file since it does not have this tool.

If you are manually editing the file, open it and look for the subnet entry. It should look something like the following:

subnet 172.16.112.0 netmask 255.255.255.0 {
  range 172.16.112.128 172.16.112.254;
  option broadcast-address 172.16.112.255;
  option domain-name-servers 172.16.112.1;
  option domain-name localdomain;
  default-lease-time 1800; # default is 30 minutes
  max-lease-time 7200; # default is 2 hours
}

The range entry specifies the range of IP addresses that VMware dynamically allocates to its VMs. In this case the range is 172.16.112.128-172.16.112.254.

You now want to pick a static IP address that has the same first three components of this address and a final component that does not overlap with the range 128-254. You should also not pick the numbers 0 or 1. An example candidate here would be 172.16.112.100.

When you have picked this address you then need to edit the dhcpd.conf file. You will need administrator privileges on your machine to edit this file. On OS X, for example, you will may need to change the permissions of the file and its enclosing directory (/Library/Preferences/VMware Fusion/vmnet1/) to allow writes by the modifying user before using an editor such as TextEdit. You can add write privileges to the file and directory by right clicking on each and selecting the Get Info option and then add the current user with read and write privileges in the Sharing and Permissions section.

Add the following lines at the end of the dhcpd.conf file:

host epad-vm {
  hardware ethernet XX:XX:XX:XX:XX:XX;
  fixed-address 172.16.112.100;
}

The hardware ethernet address should be the MAC address you noted earlier after running ifconfig inside the ePAD virtual machine (00:0C:29:6D:42:4D in our example). Here epad-vm is the name of the ePAD VM, not its host name. The fixed-address entry should be the static IP address that you picked. After editing, save the file.

Now shut down and restart VMware so that it picks up the new DHCP configuration information.

On Windows systems you may need to restart the VMware DHCP service using the Windows Services tool in the Control Panel.

Restart the ePAD VM, log on as user epad, and start a terminal (Applications->System Tools->Terminal) and again run ifconfig on the command line. The information returned should look something like the following:

eth0 Link encap:Ethernet HWaddr 00:0C:29:6D:42:4D
inet addr:172.16.112.100 Bcast:172.16.112.255 Mask:255.255.255.0

Verify that the inet addr entry is the static IP address you specified in the DHCP configuration file earlier (172.16.112.100 in our example). If not, double check both the IP address and the MAC address specified in the DHCP configuration file. Your ePAD VM should now be permanently allocated to that IP address on the host machine (and will only be accessible from the host machine).

The final step is to map the name epad-vm to that IP address. On OS X and other Unix-based systems this involves editing the /etc/hosts file. On Windows the file is under the system root directory and is called \system32\drivers\etc\hosts. You will likely need administrator privileges to edit these files. Open this file and add a line like 172.16.112.100 epad-vm. You should then be able to refer to the ePAD virtual machine using this name.

Log on to the virtual machine as user epad and start a terminal (Applications->System Tools->Terminal).

Then start the ePAD server as follows:

cd ~epad/DicomProxy/bin
./epad-start.sh

Restart the ePAD virtual machine and then go to a web browser. (Currently only Firefox and Chrome are supported.) Enter http://epad-vm:8080/epad and verify that ePAD appears. There are two existing ePAD accounts, admin and guest. The passwords are the same as the user names.

Installing ePAD using Docker (Beta)

Currently installation using Docker is only supported on Linux or Mac OS X.

  • First install Docker on your host system.
  • Linux users - make sure docker is configured to allow it to be run without sudo (see docker without sudo).
  • Make sure wget is installed on your system (mac users can get it here)
  • Download the epad docker script from the download link
  • Mac users should start a Docker terminal window (this will also create/start a VirtualBox default instance)
  • You need to make the script executable
    chmod +x epad_docker.sh
  • Create a directory for installing epad and copy the script to that directory
  • cd to the directory and run the script
    ./epad_docker.sh
  • Answer 'y' to the two questions about installing mysql
  • The script will download and run all docker images needed by ePAD
  • Use your browser to verify that ePad has been installed (Please give it a minute or two to start).

Notes:

  • The script creates four docker containers:
    • mysql
    • exist
    • dcm4chee
    • epad_web
  • The docker containers will use the following tcp ports: 8080, 9080, 8899 and 11112.
  • DicomProxy/bin contains scripts to stop and start the docker containers.
  • Mac users may wish to stop the VirtualBox after stopping docker epad
    docker-machine stop default

Network-Accessible VM

In general, you will most likely need to ask your local IT staff set up an ePAD VM in this mode.

This installation could be on a cloud platform (like Amazon AWS or MS Azure) that runs Centos servers or your own VMWare cluster

A VMWare Cluster will have tools to import the VMWare Image. For the other cloud platforms check if they support importing the VM Image in OVF format (both Amazon and Azure have tools to do so)

In this mode, after importing the image and creating a Centos instance, the ePAD server configuration file should be updated to reflect the fully-qualified host name or IP address of the VM.

The application uses the following tcp ports: 8080, 9080, 8899 and 11112. In order to access and use ePAD, only 8080 needs to be open in the Firewall. 11112 should be open if you wish to push dicom images directly to dcm4chee. 9080 can be open, if you wish to access the dcm4chee web interface and 8899 if you wish to access the eXistDB web interface, but are not required for using ePAD.

Basically, the ePAD server's configuration file, which is called ~epad/DicomProxy/etc/proxy-config.properties, should be updated to reflect the IP address or host name of the VM on the network. There are a number of attribute-value property pairs in this property file that are currently set to epad-vm, which is the default host name of the ePAD server. If a different host name is selected or if you want to fully qualify the host name you should change these entries to reflect the new name.

Any changes to this configuration file requires a restart of the ePAD server.

Log on to the virtual machine as user epad and start a terminal (Applications->System Tools->Terminal).

Then start the ePAD server as follows:

cd ~epad/DicomProxy/bin
./epad-start.sh

Restart the ePAD virtual machine and then go to a web browser. Enter http://epad-vm:8080/epad and verify that ePAD appears. There are two existing ePAD accounts, admin and guest. The passwords are the same as the user names.