This page will briefly discuss the development workflow for developing Open Web Apps. For a description of what Open Web Apps are, see the wiki page. Much of this document is derived from the Developing an HTML+JS Open Web App Quickly wiki page.

1. Setup OpenMRS

In order to develop Open Web Apps, you will need an OpenMRS server running locally. The ways to do this are described below.


The quickest and easiest way to set up a server locally is to download the latest standalone server from the OpenMRS downloads page. You will need Java 1.7+ to run the standalone server. Once it's downloaded, extract the ZIP archive and run the jar file either by double clicking it or executing the following command:

java -jar openmrs-standalone.jar

The first time you run the server you will be asked if you want to insert dummy data into the system. This is recommended if you want some data to play with.


Another easy way to run an OpenMRS server is to use the OpenMRS SDK. To use this method you must have Java 1.7+ and Maven 3+ installed. To install and configure the OpenMRS SDK, run the following:

mvn org.openmrs.maven.plugins:openmrs-sdk-maven-plugin:setup-sdk

To create a new OpenMRS Platform server, run the following:

 mvn openmrs-sdk:setup-platform -DserverId=platform -Dversion=1.11.5

Finally, navigate to the server directory (probably ~/openmrs/platform) and run:

mvn openmrs-sdk:run

It is also possible to run a Reference Application server using the SDK. See the SDK docs for instructions on how to do this.


The enterprise install is usually meant for production environments, and involves installing MySQL and Tomcat manually, then downloading the OpenMRS Platform WAR file from the OpenMRS downloads page and deploying it to Tomcat. See the full documentation here.


To set up and instance of the OpenMRS Platform using Docker, follow the instructions in the README file in this repository. To support rapid local deploys, you'll need to make the following change to your docker-compose.yml file:


  build: tomcat
    - "8080:8080"
  container_name: openmrs-platform-tomcat
    - openmrs-platform-mysql
+  volumes:
+    - /host/location/of/owadata:/usr/local/tomcat/.OpenMRS/owa
  build: mysql
    - "3306:3306"
  container_name: openmrs-platform-mysql


This will create an owadata directory at /host/location/of/ on your Docker host and map that to the Open Web Apps data directory in the container. Once you've scaffolded your app (see section #3 below), edit the LOCAL_OWA_FOLDER variable in gulpfile.js to point to this directory in order to support local deploys.

2. Install the Open Web Apps module

This is described on the Open Web Apps Module page. It's the same as installing any other other module

3. Scaffold Your Open Web App

A boilerplate Open Web App along can be scaffolded using the Yeoman OpenMRS OWA generator. You will need NodeJS 6+ installed to do this. See the install instructions here.

Once you have NodeJS installed, you need to install Yeoman, as follows: 

npm install -g yo

You can then install the generator:

npm install --global @openmrs/generator-openmrs-owa

Next, create a directory for your Open Web App and change into it. Then run the following to scaffold your app:

yo @openmrs/openmrs-owa

This will start up the Yeoman generator. The output should be something like:


Follow the options in the Yeoman generator in order to scaffold the app. Depending on your setup options it might look something like this when you are done: 



Congratulations you have successfully scaffolded your app!

4. Development

All the Open Web App files are in the app directory, everything else is used for building and managing packages. Any files you add manually must be added in the app directory.

The app/manifest.webapp files contains the information that OpenMRS needs to host your app. See the Open Web Apps Module documentation for details. The launch_path property contains the path to your app entry point. This is the page that will be loaded when you click on your app in OpenMRS.

Building The App

To build and package your app in a distributable file, use npm Webpack.  


npm run build:prod


This creates a zip file in the app directory. You can then upload this to an OpenMRS implementation using the Open Web Apps Module.

Local Deployment

To speed up the development workflow, we can deploy directly to the app data directory on the filesystem, again using using npm Webpack:


npm run build:deploy

 The app should now show up in your OpenMRS implementation (Administration -> Open Web Apps Module -> Manage Apps) and will look something like this: 



If you have issues using Webpack to deploy the app, ensure that the deploy directory is correct. Open the config.json file in the apps directory and make sure that LOCAL_OWA_FOLDER points to the correct directory. For example: 

"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.5/appdata/owa",


Using Browsersync

npm can use Browsersync to watch the files as you development and dynamically reload the app as you make changes to the code. Each time you save a file in the app's directory, the app will reload and display in the browser. This is an extremely useful tool. To use browsersync run the following command in your app's directory: 

npm run watch


If you have issues getting browsersync to work, ensure that the app is being injected. Open the config.json file in the app directory and make sure that APP_ENTRY_POINT points to the correct path. Your config.json file should look 

"LOCAL_OWA_FOLDER": "/Users/username/openmrs-standalone-2.5/appdata/owa",
"APP_ENTRY_POINT": "http://localhost:8081/openmrs-standalone/owa/appList/index.html"

5. Add Home Screen Link

Since you've built a standalone app, you want to let people access it from the OpenMRS home screen. In the Standalone or the Reference Application, you can do this by going to System Administration -> Manage Apps -> Add App Definition and then adding a definition like:


    "id": "listApp",
    "description": "Demo App",
    "order": 0,
    "extensions": [
            "id": "demoapp.homepageLink",
            "extensionPointId": "org.openmrs.referenceapplication.homepageLink",
            "type": "link",
            "label": "Demo App",
            "url": "owa/demoapp/index.html",
            "icon": "icon-plane",
            "requiredPrivilege": "Replace with a privilege name, or else remove"


You can see the available icons at

For more details about Adding Icon to Reference Application Homepage, just visit Adding OWA Icon to the Reference ApplicationHomepage