Reference Application Setting Up Development Environment

Background

OpenMRS has always had a web application component however, the web application focused primarily on basic administrative features and lacked most content, leaving it up to modules and administrators to provide EMR functionality and content.  The Reference Application, on the other hand, strives to provide more of a starter set of content along with basic EMR functionality (e.g., registration, basic reports, etc.).  The web application framework upon which the Reference Application is based comprises a handful of new modules that run within the existing web application and provide a new, Spring and Groovy-based framework for more agile web development. The pages that have been overriden in the reference application at the time of writing this are the home and login pages.

Motivation to build the reference application was due to the work done for the Mirebalais project so we wanted to continue with that momentum to develop the reference application. Reference application development is different in the follow ways:

• Development is expected to be done via modules
• We are using the a custom UI framework which involves usage of of spring controllers but used a little differently and groovy server pages(GSPs) as the view technology, for more about the framework and using it see UI Framework, this is intended to make development easier, faster and more fun.
• Development is strongly CI driven, if any anything gets broken on our bamboo server, fixing the build becomes the top priority.
• We use Compass and Sass to build our CSS
• We are using several useful Javascript libraries in the UI

IDE

You should use an IDE to do OpenMRS EMR development. There are core OpenMRS developers who use both IntelliJ and Eclipse.

Please do not commit any IDE-specific files to the source code repository. If you are creating a new Reference Application module, or you are the first to work on a module with your particular IDE, please modify the .gitignore file as appropriate (e.g. ignore *.iml and *.idea)

IntelliJ

We suggest that you create an "OpenMRS EMR" Project and you import OpenMRS core, as well as any OpenMRS modules you will be working on (including new ones you create) as IntelliJ "Modules" in that Project.

We suggest using git at the command line to clone modules from github and then using "Import Modules" to add them into your IntelliJ project.

Eclipse

We suggest that you clone OpenMRS core and modules with git at the command line and import them into Eclipse with the m2e plugin. If you do not know how to work with Eclipse see Getting Started as a Developer for specific instructions.

Check Out OpenMRS Core

The Reference Application is built on top of the latest release like of the OpenMRS core codebase (currently 1.9.x).

We will expect to make bugfixes to the OpenMRS core as we work on the Reference Application, but we may not add new features to core, since those are not backported to the already-released lines.

You need to check out OpenMRS so that you can run OpenMRS under jetty. This is documented elsewhere on the wiki. We recommend that you make your own fork of the main repository, so that you can submit bugfixes as pull requests.

After cloning the git repository check out the 1.9.x branch (e.g. "git checkout -b 1.9.x origin/1.9.x")

Database

In order to be able to run OpenMRS core you need to install MySQL.

Building the distro

Run Configuration

To run OpenMRS, use the "mvn jetty:run" goal in the webapp module of openmrs-core.

In eclipse you can set this up as a Run Configuration like:

• Base directory:

   ${workspace_loc:/openmrs-webapp} 

• Goals: jetty:run

Set the following VM options to use our preferred webapp name, give OpenMRS sufficient memory, and enable rapid UI development (replacing with correct pointers to the source code you have checked out):

-Dwebapp.name=refapp
-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m
-DuiFramework.development.referenceapplication=/Users/djazayeri/Documents/git-repositories/openmrs-module-referenceapplication

Running the Reference Application in a production-like environment.

The target environment for CI, and other servers is Tomcat7 running on Ubuntu 12.04.  If you'd like create a virtual machine in your environment for testing, see the wiki page: Developer How-To Launch a Local Instance of the Reference Application.

Typically our CI setup will constantly be building the latest versions of the above modules. The only way to be sure you have the equivalent build yourself is to update and build all of these modules regularly.

Modules

Most development work on the reference application can be done without needing to check out all the code for all modules in the application. You should be able to implement new features by working on the specific module that includes the app in question.

To run the reference application, you need compiled versions of all modules in the reference application distro. To get these, you need to clone https://github.com/openmrs/openmrs-distro-referenceapplication and run mvn clean package. This command will produce a zip file with omods in the target directory which you can unzip into the module directory in your Application Data directory (skip the war file). You need to restart OpenMRS to have all the modules installed and started.

If you want to get code of some modules you need to fork them and clone. Here's a partial list of modules included in the Reference Application:

(TODO: Continually update this list of modules.)

If you are a core developer, you will most likely need to clone the following modules:

• App Framework
• UI Commons
• App UI
• Core Apps
• Reference Application
• EMR API

All modules can be built by running mvn clean install. If some module is not building for you, please check its status in our CI. If it is green, then it means that it is only your local problem and you need to resolve it yourself. If you need assistance, please contact us.

Contributing code to the core modules

If you expect to contribute any bug fixes to OpenMRS core and the modules, follow the fork + pull-request git workflow at Using Git

Maven versions plugin

Use the following command to update the pom.xml for the openmrs-distro-referenceapplication repository if you need to have the latest versions of all the modules included in the Reference Application.

mvn versions:update-properties -DallowSnapshots=true -DexcludeProperties=uiframeworkModuleVersion,openMRSVersion

If you'd like to push this change to the master branch in GitHub, please discuss the changes on the dev-refapp@openmrs.org mailing list before pushing.

Handful commands:

git clone https://github.com/YOUR_ACCOUNT/openmrs-module-appframework

git remote add upstream https://github.com/openmrs/openmrs-module-appframework

mvn clean install

For more info on GIT see Using Git.

Developing CSS

We use Compass and Sass to build our CSS in the reference application.

• Every time you do a maven build (in the process-resources phase), the contents of omod/src/main/compass/sass will be compiled into omod/src/main/resources/styles (so they can be picked up by the UI Framework)
• If you are doing active CSS development, and want these files compiled every time you change them, do this from the omod folder:

mvn process-resources -Pwatch-sass

Continuous Integration

We are using Bamboo, running at https://ci-stg.openmrs.org. We have 2 servers one at http://devtest01.openmrs.org:8080/openmrs/login.htm  which the UI tests are run against and then http://devtest02.openmrs.org:8080/openmrs/ where you can go to test the latest builds, the scripts that deploy to these servers are run after every commit, we encourage devs to look at the CI server a couple of minutes after they commit their code to ensure no plans are broken as a result of their commit. After completing significant functionality, you should manually verify that it works there. Note that deployment to devtest02 only happens if the ui tests are run successfully against devtest01

Writing your own module on top of OpenMRS EMR

• Create the module project following steps described at Using the Module Maven Archetype
• If you intend to host the module project on github, you will need to create a repo for it on github at Creating a github repo, be sure to select the owner of the repo, typically it should be openmrs.
• To setup the module to use the UI framework see Using the UI Framework in Your Module. In your omod sub project you might need to also include dependencies for uicommons, appui, uilibrary, appframework modules
• To share your code on github, from the command line, go to the module project directory and run the git commands below:

  • git init
    
    git remote add origin https://github.com/openmrs/openmrs-module-moduleId.git
    
    git pull --rebase origin master
    
    git push origin master

    Remember to exclude any IDE specific files