As of March 2017, the resources mentioned on this page are outdated/ no longer maintained. The OpenMRS SDK is now the preferred method for launching a local instance of the Reference Application.



Developers have the ability to deploy and test changes to any of the Reference Application's modules before pushing those changes to GitHub.  The mechanism makes use of Vagrant and Puppet to provision test environments on the developer's workstation with one command.


NOTE FOR WINDOWS USERS:  Make sure you clone your repository with the git config option core.autocrlf=false to preserve Unix-style line breaks in scripts and properties files.

The following software will need to be installed on your system.

Details on virtual machine


Process to launch an instance with latest code from HEAD

  1. Clone / Pull the Reference Application's Distro repository.
  2. CD to the base directory of that clone.
  3. Run the command 'mvn clean package' to create a zip file of the war and omods for the Reference Application.

  4. Run the command 'vagrant up'

  5. Browse to http://localhost:8080/openmrs to access the application
  6. OPTIONAL: When done testing run 'vagrant halt' to stop the virtual machine.


Process to update an instance with work in progress (aka uncommitted) code changes

  1. Run a 'mvn clean install' under the module to which you want to test changes.

  2. CD to the base directory of the Reference Application's Distro module.
  3. Run the command 'mvn clean package'
  4. Run the command 'vagrant provision' (if your test machine is already running) or 'vagrant up' if your test machine is "powered off."
  5. OPTIONAL: When done testing run 'vagrant halt' to stop the virtual machine.


An explanation of useful vagrant commands.