New Installation

The following describes how to install OpenVPMS from scratch and assumes that you have downloaded it and unpacked its zip file.

If you have not installed the other required software, see Requirements.

The headings below are:

Note that in the following the directory or folder separator character is shown as /, following unix conventions. On Windows, replace / with \. e.g. given:
change to:

Directory structure

The OpenVPMS installation has a single top-level directory named:
where XXX indicates the version.

This will be referred to as <OPENVPMS_HOME> in the remainder of this document. This directory has the following sub-directories:

Name Contents
bin a number of tools used to load data into OpenVPMS
conf configuration files for the tools in ../bin
db MySQL SQL scripts to create the initial database
import data to import into OpenVPMS
lib jars used by the tools in ../bin
reports document templates for reporting
update data and scripts to migrate from earlier versions of OpenVPMS
webapps  the OpenVPMS web applications





MySQL connector

The MySQL Connector/J JDBC driver needs to be downloaded from:
It is typically named mysql-connector-java-5.1.<x>.zip or mysql-connector-java-5.1.<x>.tar.gz where <x> represents the minor version number.

The JDBC driver in the archive is named:

This needs to be copied to:

  • the Apache Tomcat library directory: <TOMCAT_HOME>/lib
  • the OpenVPMS library directory:  <OPENVPMS_HOME>/lib

In the above, <TOMCAT_HOME> refers to the directory where Apache Tomcat is   installed. On Windows, this will be something like:
    C:\Program Files\Apache Software Foundation\Tomcat 7.0

Database setup

To create the OpenVPMS MySQL database, run the following in a shell prompt
  > cd <OPENVPMS_HOME>/db
  > mysql -u admin -p < createdb.sql
  > mysql -u admin -p openvpms < db.sql


  • replace 'admin' with a user that has administrator privileges in MySQL.
  • the createdb.sql script creates an 'openvpms' user that only has privileges to connect from localhost. If the MySQL database is a different host to that running Tomcat, change the createdb.sql script to uncomment:

    # GRANT ALL PRIVILEGES ON openvpms.* TO 'openvpms'@'%'

To improve security, the '%' can be limited to the host that Tomcat will connect from.

Next, run the 'dataload' script. This provides two options, 'base' and 'setup'. The former loads a base database setup in preparation for data migration. The latter contains a default setup suitable for a new installation.

  > cd <OPENVPMS_HOME>/bin
  > dataload setup

Web application installation

To install the OpenVPMS web application:

  1. Copy <OPENVPMS_HOME>/webapps/openvpms.war to the <TOMCAT_HOME>/webapps  directory.
  2. Start Apache Tomcat if it is not running

OpenOffice installation

OpenVPMS uses OpenOffice to perform reporting, printing and document conversion.
Install it as per your platform's requirements and then:

  1. Add it to the PATH of the user that runs Apache Tomcat.
    The installation path differs by platform and OpenOffice version. For OpenOffice 4 on Windows, the default installation path is:

           C:\Program Files (x86)\OpenOffice 4\program

    Windows users can find instructions for changing the PATH here.      

  2. Verify it can be run as that user. From a command prompt, enter:
    This should start OpenOffice.

Document Templates

Document templates used for invoices, payments etc., are located in:

These need to be loaded prior to use. This can be done using the 'templateload' script. e.g:

  > cd <OPENVPMS_HOME>/bin
  > templateload ../reports/templates-X.xml

Where X is:
       A4 to load the A4 template set
       A5 to load the A5 template set
       Letter to load the Letter (ie US) template set


  • If a template with the same name has been already loaded, it will be replaced. More precisely, templates with the same name AND same content name will be replaced. Hence, if you have a template named Invoice, with content invoice-BE.jrxml, this will not be replaced but a new template named Invoice with content invoice.jrxml will be created.
  • Not all templates are available in all formats, however a complete set is loaded. Thus if you load the A5 set you will find that some templates are in A4 format. To clarify the situation, the description field indicates the paper size if it is not A4. eg " Medical Records (A5)"
  • Three drug label formats are available, Dymo, Epson, and 1.8x3.1.  If you load the Letter set you will get the latter, if you load A4 or A5 you will get Dymo.
  • Not everything is loaded. For example the Samples and the Patient Reminder Post Cards are not.

After installation, templates can be updated using via Administration|Templates.

The templates need to be customised to add practice logos etc. Templates with a:

  • .doc or .odt extension can be customised in OpenOffice Writer or Microsoft Word
  • .jrxml extension can be customised in Jaspersoft Studio

See also Introduction|Reporting, Reference|Reports and Forms, and Administration|Templates.

Testing the installation

To test the installation, open up your Internet Browser and enter the address:


Login to OpenVPMS using user admin and password admin


Optional steps

OpenVPMS ships with optional data that can be loaded as required. This includes:

  • Security roles

The basic installation grants all functionality to all users. To restrict this, load the roles.xml file

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/roles.xml

  • VeNom presenting complaint and diagnosis codes

These are standardised codes that can be used to classify patient Problems. These can be loaded using:

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/VeNom-lookups.xml

  • Australian states and suburbs

These can be loaded using:

  > cd <OPENVPMS_HOME>/bin
  > dataload -f ../import/data/postcodesAU.xml


Syndicate content