Setting up a Bahmni Dev Environment for OpenMRS Developers

WARNING

This page has been Archived, and is obsolete. It is available on the Bahmni wiki only for reference and historical purposes.

Instead of deleting a page, we prefer to "archive" it, so that it is still available to people who have bookmarked the page.


This document describes how to set up a Bahmni developer environment, and is aimed at developers with prior OpenMRS experience. The goal of this documentation is to describe how to set up Bahmni to co-exist with the OpenMRS 2.x Reference Application, and do development on both. This aspect is not complete yet.

The Bahmni EMR is a client-side application, built in AngularJS and HTML, and it interacts with the OpenMRS back end using REST web services. (Bahmni also includes a regular OpenMRS module called bahmni-core that provides additional server-side functionality.)


This document was written for Mac OS X, but should be equivalent on Linux.

If you are not familiar with Docker, then this document might be easier for you: Setting up Virtual Box and Dev Environment using Vagrant


Prerequisites:

  • docker and boot2docker    (boot2docker is used for running docker on Mac or Windows. On Linux you don't need it.)

  • docker-compose    (see Bahmni Using Docker for instructions on setting this up)

  • node.js

  • Java 7

  • Maven (version?)

  • Ruby

Setup

First, install some additional components:

npm install -g bower
npm install -g grunt-cli
gem install compass         // you may need to use sudo ...


Edit your /etc/hosts file and add the following line (so you can refer to that machine as "dockerhost"):

192.168.59.103  dockerhost


We need to set the BAHMNI_PROFILE environment variable to indicate which configuration of Bahmni to use. Start off with “mrs”, which means a minimal setup without LIS or ERP. Add this to your ~/.bashrc file: 

export BAHMNI_PROFILE=mrs

Then run:

source .bashrc


Now, create the folder where you will check out the Bahmni codebase at ~/bahmni-code, and from that folder:

git clone https://github.com/Bahmni/default-config.git
git clone https://github.com/Bahmni/openmrs-distro-bahmni.git
git clone https://github.com/Bahmni/openmrs-module-bahmniapps.git
git clone https://github.com/Bahmni/bahmni-core.git


The following command will fetch all required OpenMRS modules.

cd ~/bahmni-code/openmrs-distro-bahmni
mvn clean install


The following commands will build the Bahmni web application. From openmrs-module-bahmniapps/ui:

cd ~/bahmni-code/openmrs-module-bahmniapps/ui
npm install
bower install
grunt


Now, go to the directory where you want to install the bahmni-docker setup code (e.g. ~/code) and do:

git clone https://github.com/Bahmni/bahmni-docker

Open a boot2docker shell, and from the bahmni-docker folder, run:

./bahmni install

That will take a while (it needs to download hundreds of megabytes, and configure things). If it fails, clean and try again:

./bahmni clean
./bahmni install

Next (still from the boot2docker shell and the bahmni-docker folder) run:

./bahmni start


The other helpful commands, that you do not need to run now are:

Do not run these now
./bahmni stop
./bahmni restart    // only restarts tomcat and apache; not the same as stop + start

At this point you should see the Bahmni app (which is running on Apache) at https://dockerhost/bahmni/home/. Log in as superman/Admin123

The underlying OpenMRS application (running on Tomcat) is at http://dockerhost:8080/openmrs. (Note: if you log in using the legacy OpenMRS UI, and then try to visit the bahmni app, things will break because the session won’t be set up right. If you log in this way, please log out before entering the Bahmni app.)

At this point, you have set up Bahmni, with a basic de-identified database, and the JSS Hospital configuration.

Development

Key Point

Certain files are mapped from your local machine into the docker containers, which allows you to do development in your local environment, and have them served up via docker.
You can see the specifics at bahmni-docker/profiles/{{PROFILE}}.yml , for example:

 - ~/bahmni-code/default-config:/var/www/bahmni_config
- ~/bahmni-code/openmrs-module-bahmniapps/ui/app:/var/www/bahmniapps
- ~/bahmni-code/openmrs-distro-bahmni/distro/target/distro:/root/.OpenMRS/modules

Development on the Bahmni AngularJS app

You have checked out the Bahmni application code (remember, it’s a client-side AngularJS application) on your local machine at

~/bahmni-code/openmrs-module-bahmniapps/ui/.

You may use whatever development tools you prefer, for editing html + js + css. If you are going to be working on both client-side and server-side code, you’ll probably want to use a Java IDE like IntelliJ or Eclipse. But if you’re purely working on the client-side app you can use something more web-focused.

The apache docker container is configured to serve up files directly from where you have the code checked out, so usually editing a file and refreshing the web browser is enough to see your changes.

Editing HTML files

You can directly edit HTML files and see the changes.

For example, edit the file ~/bahmni-code/openmrs-module-bahmniapps/ui/app/home/views/login.html by changing the Login header text, you will see a change reflected at https://dockerhost/bahmni/home/ (make sure you’re logged out, of course, or you won't see the login screen.)

Editing JS files

You can directly edit javascript files and see the changes.

For example, edit the file ~/bahmni-code/openmrs-module-bahmniapps/ui/app/home/controllers/loginController.js by adding console.log(“Hello, world.”);

Editing CSS files

In Bahmni, CSS is written using SASS, and therefore after you edit a .scss file you need to compile everything by going to ~/bahmni-code/openmrs-module-bahmniapps/ui and running:

grunt

For example, edit the file ~/bahmni-code/openmrs-module-bahmniapps/ui/app/styles/bahmni-helper/_base.scss by changing the color of the body element from $text to #ff0000, then build with grunt.

Developing OpenMRS Java modules

The OpenMRS modules folder in the tomcat docker container points to the local folder

~/bahmni-code/openmrs-distro-bahmni/distro/target/distro

The git repository that you checked out is ~/bahmni-code/openmrs-distro-bahmni. This mainly contains instructions that tell maven how to download OpenMRS omod files. You can see the specifics in ~/bahmni-code/openmrs-distro-bahmni/distro/pom.xml.

The actual code behind all these omod files lives elsewhere. Many of them are common OpenMRS modules, and a few are Bahmni-specific. Whenever you run “mvn install” on the distro project, it will fetch all the omods using maven. In particular this means that if make changes to a module that the distro includes a snapshot version of (e.g. emrapi) and build it locally, and then you do “mvn install” on the distro, it will fetch your just-built snapshot of that module.

 Usually you would make changes to a single module at a time, and not need to update all the modules in the distro. Once you have built your module (with mvn install), you can manually copy the omod file into ~/bahmni-code/openmrs-distro-bahmni/distro/target/distro (making sure to delete the old version if necessary).

 [ To do: describe the quick scripts for copy-docker ]

 Any changes that you make in ~/bahmni-code/openmrs-distro-bahmni/distro/target/distro will not be immediately reflected. You have to restart the tomcat docker container, by doing (from the boot2docker shell and your bahmni-docker folder):

./bahmni restart

(This “restart” command actually only restarts the tomcat and apache containers, but not the mysql one; this is faster, but note that it is not exactly the same as doing “stop” and “start”.)

Advanced Topics

Watching tomcat logs

You can use the “docker log” command to watch the OpenMRS logs in the same way you’d watch the console when doing jetty:run, or catalina.out in a direct tomcat installation. 

From your boot2docker shell, in the bahmni-docker folder, run:

docker ps
 
// this will output multiple lines; find the one that has bahmni/web, something like:
3ba7f43f833f bahmni/web:latest "/root/.OpenMRS/setu

...from this output, you need to copy the container id of the bahmni/web, in this case the container id is 3ba7f43f833f.

Once you know the container id, you can run the command:

docker logs -f <container id>

If you need more complete access to the docker container running tomcat (as if you were SSHing into the box) you can run:

docker exec -it <containerid> /bin/bash

Connecting to MySQL

You can connect to MySQL running in its docker container with any MySQL client. Just set up a connection like:

host: dockerhost
port: 3306
user: openmrs-user
password: password

Debugging

The tomcat docker container is set up to allow remote debugger connections on port 8000. In order to debug, set up a run configuration in your IDE to connect to “dockerhost” on port 8000.

To verify that this is working you can try putting a breakpoint on the first line of the method: org.bahmni.module.bahmnicore.web.v1_0.controller.BahmniDiagnosisController#search

Then, when you open a patient in the Clinical app, the breakpoint should be triggered. (You will need to register a patient and start an OPD visit for them first.)




Still To Do

Comment on Bahmni using Java 7, and compatibility with other OpenMRS modules

Describe how to run Bahmni + Reference application. (This involves deciding how to deal with incompatible concepts and sources.)

On this page

The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)