Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack


Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Specified MySQL version needed, added note about APP_ENTRY_POINT, added information about possible dependency issues with Angular, added general tips regarding technologies to use and design decisions.


Another easy way to run an OpenMRS server is to use the OpenMRS SDK. To use this method you must have MySQL 5.6, Java 1.7+ and Maven 3+ installed. Newer versions of MySQL, even with compatibility options, will not work. To install and configure the OpenMRS SDK, run the following:


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: 

Code Block
titleSupport Local Deploys to Docker
  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.


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: 


Image Removed


Congratulations Image Added

Ensure that the APP_ENTRY_POINT inside webpack.config.js is set to the proper location of your OWA's index.html. Congratulations, you have successfully scaffolded your app!

AngularJS Dependency Changes

It's possible that you can encounter TypeErrors if your OWA is using Angular 1.x. Inside package.json in the OWA's root folder, remove the ^ before the version number of each dependency related to Angular. Run npm install afterwards to install the correct versions of those dependencies. See here for more information. 

You may also have to remove the following snippet found inside home.js if you are still encountering issues:

Code Block
titleDependency code snippet
.config(['$qProvider', function ($qProvider) {

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.

General Tips

If you're building your OWA with Angular, all code should be inside components and designed in a modular manner. This will help facilitate an upcoming migration to a more recent version of Angular. 

If you're building your OWA with React, please refer to and follow the style guide. There are also React Components available for use.

For the latest information on which technologies to use, check the OpenMRS Radar which is updated quarterly. 

Building The App

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


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


Code Block
titleScaffold Open Web App
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: 


Code Block
titleBuild App
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 


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:


Code Block
titleHome Page Link Config
    "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"