This section describes how to install OpenVPMS.
The required software is documented in Requirements.
There are three installation procedures:
If you are doing a new install, you should also read:
Other useful information can be found in the following:
OpenVPMS is designed to be used with Firefox, Chrome, or Safari.
The Context Sensitive Help facility provides help when you press Alt-F1 on most screens.
By default, the help is displayed in a separate browser window. If you want it displayed in a tab rather than a new window, try the following:
Note that both Context Sensitive Help and Print Previews are treated as pop-ups by browsers and may be blocked. You will need to enable pop-ups for your OpenVPMS site.
OpenVPMS doesn't directly support data migration from other veterinary practice systems.
It does however provide a plugin for Pentaho Data Integration (PDI, aka Kettle) that can be used to get data into OpenVPMS.
At this stage, only PDI 3.2 is supported. This can be obtained from here.
Extract this zip file to a directory. This will be referred to as <PDI_HOME>.
To install the OpenVPMSLoader plugin:
See also Implementors Forum|Data Migration
Note that PDI 3.2 needs to use the 32-bit Java JVM. If you have previously installed the 64-bit version for Tomcat to use then you will also need to install the 32-bit version for PDI.
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:
<OPENVPMS_HOME>/lib
change to:
<OPENVPMS_HOME>\lib
The OpenVPMS installation has a single top-level directory named:
openvpms-release-XXX
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 |
The MySQL Connector/J JDBC driver needs to be downloaded from:
http://dev.mysql.com/downloads/connector/j/5.1.html
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:
mysql-connector-java-5.1.<x>-bin.jar.
This needs to be copied to:
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
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
NOTES:
# GRANT ALL PRIVILEGES ON openvpms.* TO 'openvpms'@'%'
# IDENTIFIED BY 'openvpms' WITH GRANT OPTION;
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.
e.g:
> cd <OPENVPMS_HOME>/bin
> dataload setup
To install the OpenVPMS web application:
OpenVPMS uses OpenOffice to perform reporting, printing and document conversion.
Install it as per your platform's requirements and then:
C:\Program Files (x86)\OpenOffice 4\program
Windows users can find instructions for changing the PATH here.
Document templates used for invoices, payments etc., are located in:
<OPENVPMS_HOME>/reports
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
NOTES:
After installation, templates can be updated using via Administration|Templates.
The templates need to be customised to add practice logos etc. Templates with a:
See also Introduction|Reporting, Reference|Reports and Forms, and Administration|Templates.
To test the installation, open up your Internet Browser and enter the address:
http://localhost:8080/openvpms/app
Login to OpenVPMS using user admin and password admin
OpenVPMS ships with optional data that can be loaded as required. This includes:
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
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
These can be loaded using:
> cd <OPENVPMS_HOME>/bin
> dataload -f ../import/data/postcodesAU.xml
OpenVPMS can be installed on either a unix system (most commonly a Ubuntu server), or a Windows system. For Windows, for small practices you can install on a desktop or laptop running Windows 7 or 8; for larger practices it may be better to use a Windows Server operating system.
OpenVPMS requires the following to be installed:
Download the MySQL Community Server 'Generally Available (GA) Release'.
On Windows, the MySQL installer may require that the Microsoft .Net Framework 4 be installed. This is available from:
http://www.microsoft.com/en-au/download/details.aspx?id=17851
The MySQL Workbench is not required by OpenVPMS itself, but if you are going to do any report development, then you will find that the Workbench’s ability to build and test SQL queries is very useful. You can download it from http://dev.mysql.com/downloads/workbench.
This may be included in the MySQL server installation.
On Windows, select the 32-bit/64-bit Windows Service Installer
If you have installed Java 8, you must use Tomcat 7.0.53 or higher.
NOTE: this replaces iReport Designer which is no longer under active development, and does not work with Java 8. Sites running Java 7* can continue to use iReport Designer, but should use 5.0.4 or higher.
* Java 7 will no longer be updated by Oracle as of April 2015. OpenVPMS 1.8 will continue to work with Java 7, but users are encouraged to update to Java 8 to receive bug fixes and security enhancements. Java 8 will be required by OpenVPMS 1.9.
This page addresses various security related matters.
Database passwords
The default installation creates a MySQL database user named 'openvpms' with password 'openvpms'.
This password should be changed. This can be done with the mysql utility with the command:
set password for 'openvpms'@'localhost' = password('3f6iNF7m46w9vjc');
This should be done for each host that the openvpms user has been granted access from.
For more information see:
https://dev.mysql.com/doc/refman/5.5/en/set-password.html
The password is stored in configuration files that will also need to be updated:
Administrator password
The default installation creates an OpenVPMS user named 'admin', with password 'admin'.
This should be changed when installation is complete, via Administration|Users.
User passwords
User passwords are configured via Administration|Users. There is little restriction on what passwords may be entered, but it is recommended that strong passwords are used.
File permissions
The OpenVPMS and Tomcat installation directories should only be accessible to a single user with a strong password.
These directories contain files that could enable an attacker to gain access to the OpenVPMS web application, or the MySQL database.
OpenVPMS relies on user subscriptions to fund development.
Your subscription status is displayed on the OpenVPMS login screen. If you have not paid, a link to a payment page is displayed. On payment, a subscription key will be mailed to you.
If you have a current subscription, you can request a subscription key by emailing a copy of your receipt to subscription[at]openvpms[dot]org.
To update your subscription status, edit the Practice in the Administration|Organisation workspace and upload the new subscription key.
This section details the procedure to be used when upgrading to a new release of OpenVPMS.
The headings below are:
Having installed the new release, you may want to look at the Implementation Checklist page.
Note that in the following the directory or folder separator character is shown as /, following unix conventions. On Windows, replace / with \. e.g. given:
<OPENVPMS_HOME>/lib
change to:
<OPENVPMS_HOME>\lib
The software required to run OpenVPMS may change between releases.
Check Requirements to ensure you have the necessary software.
Back up your database prior to performing the upgrade.
This can be done using the mysqldump tool. e.g.:
mysqldump -u openvpms -p openvpms > openvpms.sql
NOTE: It is good practice to ensure that the backup can be restored to a different server, prior to performing any upgrade.
See also How To|Administration|Backup.
These instructions assume that:
1. The previous OpenVPMS installation is available in <OPENVPMS_PREV>.
e.g. on Windows:
c:\OpenVPMS\openvpms-release-1.7
2. The new installation will be located in <OPENVPMS_HOME>.
e.g. on Windows:
c:\OpenVPMS\openvpms-release-1.8
NOTE: the OpenVPMS version can be excluded from the path name, for example c:\OpenVPMS-Current Release - when upgrading you can rename this to say 'Current Release prev' . This can simplify upgrades by removing the need to change custom scripts that contain the installation path.
The previous installation should be retained until:
Upgrading from an earlier version of OpenVPMS requires data migration scripts to be run.
The scripts are located in the <OPENVPMS_HOME>/update/db directory. With the exception of the 1.5 to 1.6 release (where there was no change to the database structure), there is one sql script per release.
The sql scripts are:
migrate-1.0-to-1.1.sql
migrate-1.1-to-1.2.sql
migrate-1.2-to-1.3.sql
migrate-1.3-to-1.4.sql
migrate-1.4-to-1.5.sql
migrate-1.6-to-1.7.sql
migrate-1.7-to-1.8.sql
You need to run each relevant one in turn using the mysql utility.
Hence if you are upgrading from OpenVPMS 1.7, run:
> mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql
If you are upgrading from OpenVPMS 1.5 or 1.6, run:
> mysql -u openvpms -p openvpms < migrate-1.6-to-1.7.sql
> mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql
If you are upgrading from OpenVPMS 1.0 - you need the lot, so run:
> mysql -u openvpms -p openvpms < migrate-1.0-to-1.1.sql
> mysql -u openvpms -p openvpms < migrate-1.1-to-1.2.sql
> mysql -u openvpms -p openvpms < migrate-1.2-to-1.3.sql
> mysql -u openvpms -p openvpms < migrate-1.3-to-1.4.sql
> mysql -u openvpms -p openvpms < migrate-1.4-to-1.5.sql
> mysql -u openvpms -p openvpms < migrate-1.6-to-1.7.sql
> mysql -u openvpms -p openvpms < migrate-1.7-to-1.8.sql
Note that if you are helping test a new release, you will be getting 'snapshot' releases. It this case it is sensible to re-run the migration script for the new version. The scripts are written so that they are re-runnable.
If you are replicating your OpenVPMS database, you must ensure that row-based replication is used. The migration scripts are not compatible with statement-based replication.
Copy the MySQL JDBC driver mysql-connector-java-5.1.<x>-bin.jar from <OPENVPMS_PREV>/lib to <OPENVPMS_HOME>/lib
Load the latest archetypes by running the appropriate archload script for your platform.
Windows:
> cd <OPENVPMS_HOME>\bin
> archload
Unix:
> cd <OPENVPMS_HOME>/bin
> archload.sh
The existing web application should be removed before installing the new version.
To do this:
If you use customised versions of the standard archetypes, or have added archetypes, these will need to be loaded.
For modified versions of the standard archetypes, be sure to incorporate any changes that have been made.
You should then use archload to load these archetypes - or if you have only a few, use Administration|Archetypes|Import.
If you have customised versions of propercase.properties, help.properties, or messages.properties you need to install these in
<TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/localisation
You can simply overwrite the default propercase.properties with your own version.
However, help.properties and messages.properties will need to be edited to bring your adjustments into the current versions.
If you have a customised default.stylesheet, then the version in
<TOMCAT_HOME>/webapps/openvpms/WEB-INF/classes/style
will need to be edited to incorporate your changes.
Now restart Apache Tomcat so the above customisations get picked up and login and see that things are as they should be.
In order to take advantage of new and revised document templates, you will need to load these - see here. Note that you will almost certainly have tailored versions of the system documents (like invoices, credits, etc). Before loading the templates, you will need to check that your customised version have different names - as the notes say:
"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."
Hence, if your customised versions have the standard content names, loading the new set will overwrite your customised versions. In this case, the best approach is probably to edit the templateload xml file (ie <OPENVPMS-HOME>/reports/templates-X.xml where X is A4, A5 or Letter) to delete the lines for the templates that you do not want loaded.
If you use Pentaho Data Integration (see here) then you need perform its steps 1,2 and 3 to upgrade the OpenVPMS components.
If you have an existing system but you are installing OpenVPMS on a new machine, you essentially go through the steps for a new install, but instead of creating a new openpms database, you restore your existing one, and then upgrade that to the new release.
First you need to use mysqldump to take a backup of the database on the old machine (see Upgrade|Preparation).
Now you can follow the New Installation steps until you get to the dataload step. Instead of using the dataload utility, you use the mysql utility to restore your backup onto the new machine. This is done using the command:
> mysql -u admin -p openvpms < openvpms.sql
where admin is the name of your root user and openvpms.sql is the dump from the old machine.
You should continue with the Web Application and Open Office installation steps.
To complete the process, we need to upgrade the installation on the new machine, so we simply use the steps to Upgrade an Existing Installation.