How to install Modulus and Modulus UI

Table of Contents

This guide shows how to install Modulus and Modulus UI on your local machine.

This guide was originally written using OS X 10.10, however was revised using a Linux system. The initial version of this page was done by one of our /wiki/spaces/RES/pages/26279097 students, Richard Szczerba. I (Robby O'Connor) have left things which were still directly relevant, updated a lot of it. 

Get required credentials for OpenMRS ID

Development currently relies on OpenMRS ID dashboard for OAuth2 authentication. 

On ID Dashboard (

We can provide you with keys on, or you can host your own(will provide instructions at a later date)

E-mail helpdesk AT openmrs DOT org with the following information: 

Install Required Software

You will need: 

  • Java SE 7 (Grails Java 8 support is bad). Install it via homebrew. I am going to assume it is installed for the purpose of this guide. 
  •  MySQL
  • sdkman
  • nvm (node version manager) 

Install node 5 via nvm. Ensure everything is set up correctly first.

Install Node via nvm
$ nvm --version
$ nvm install 5  
$ nvm alias default 5 


If all is installed correctly you should see this output in the terminal when asking for "--version" of the software:

($ stands for something before you write in the terminal, i.e. this: "User:~ HostName$" is just $.)

Installed software
$ java -version
java version "1.7.0_80"
Java(TM) SE Runtime Environment (build 1.7.0_80-b15)
Java HotSpot(TM) 64-Bit Server VM (build 24.80-b11, mixed mode)

$ mysql --version
mysql  Ver 14.14 Distrib 5.5.49, for debian-linux-gnu (x86_64) using readline 6.3

$ sdk version
SDKMAN 4.0.32
$ node --version

Setting up Modulus Server

Install Grails

Run the following command in your terminal.

Install Grails
$ sdk install grails 2.3.7

Clone the Modulus Repo and Install Submodules

Navigate to where you want to save the repository and run:

Download Modulus Repo
$ git clone
$ cd openmrs-contrib-modulus
$ git submodule init
$ git submodule update

Set up MySQL Database

Using the terminal run:

MySQL Modulus Database creation
$ mysql -u root -e "CREATE DATABASE modulus"

-u stands for user called

-e stands for execute this


If you get the error ; 

MySQL Error
Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)

That means your MySQL server has stopped running. To start it run:

MySQL Server Start
$ sudo service mysql start

Create the modulus-config.groovy file

Modulus looks for config files in ~/.grails/modulus-config.groovy/opt/modulus/modulus-config.groovy, or in the classpath. It will also look for .properties files in the same locations. Custom config locations can be passed with -Dmodulus.config.location=CONFIG_PATH as a run argument.

The .grails is a hidden folder so in the terminal run and the relaunch Finder or open a new window for it to take effect:

Show hidden folders
defaults write AppleShowAllFiles YES

If you don't want to see the hidden folders any more, just change the YES to NO.

Open Finder, navigate to your home directory (probably has a house icon next to it) and open the .grails folder

If you can't find a .grails folder create it.

Into it, drag and drop the example modulus-config.groovy file and open it using a text editor.


Change the oauth.providers.openmrsid and oauthProvider.clients.clientId details with the keys you
received from completing the request and save. This must be placed in the root of .grails. 

A sample one is shown below: 

import org.openmrs.modulus.oauth.OpenMrsIdApi
grails.serverURL = "http://localhost:8080"
modulus {
       uploadDestionation = "/tmp/uploads"
       openmrsid.hostname = ""
// Overrides the default configuration in grails-app/conf/DataSource.groovy
dataSource.url = "jdbc:mysql://localhost/modulus"
dataSource.username = "root"
dataSource.password = ""
// OpenMRS ID Provider. These keys correspond to keys issued by your OpenMRS ID server.
oauth.providers.openmrsid = [
        api: OpenMrsIdApi,
        key: "5724816929358ea0349b1c30", // change this to the client id from dashboard
        secret: "67SoaGco3th1", // change this to the secret from dashboard
        successUri: "${grails.serverURL}/login/success",
        failureUri: "${grails.serverURL}/login/failure",
        callback: "${grails.serverURL}/oauth/openmrsid/callback",
        scope: "profile"
// Modulus UI Client. These keys must be known by a Modulus UI client to connect.
grails.plugin.springsecurity.oauthProvider.clients = [
                clientId: "modulus123",
                clientSecret: "modulus123",
                registeredRedirectUri: ["http://localhost:8083/auth-success.html"],
                additionalInformation: [
                        name: "Dev Modulus UI",
                        preApproved: true

Run Modulus

In the terminal navigate back your the "openmrs-contrib-modulus" and run:

Grails - Modulus
$ grails clean
$ grails refresh-dependencies
$ grails run-app

Logging in to OpenMRS on your local instance

When you visit the redirect url you set (typically it's: http://localhost:8080/oauth/openmrsid/callback) You'll be greeted with a "No login transaction found." message. No matter!

Delete the "failure" part of the url and fill in the form and allow access to your OpenMRS ID profile. If you get Error 500 with the message "Unsupported response types: [none]" all is good.

Go the grails serverURL, which has been set in the modulus-config.groovy file (i.e. http://localhost:8080). You should be logged in to openmrsid and it should greet you.

Installing Modulus UI

Clone the Modulus UI Repo.

Navigate to where you want to save the repository and run:

Download Modulus UI Repo
$ git clone
$ cd openmrs-contrib-modulus-ui

Install Grunt

Using npm* install Gruntnpm stands for Node Package Manager and comes with Node.

Install Grunt Globally
$ npm install -g grunt-cli

Next, install all dependencies needed for the project (you will need to be in the "openmrs-contrib-modulus-ui" folder):

Install Dependencies
$ npm install

Configure modulusui.conf.js

Navigate to the config folder in openmrs-contrib-modulus-ui and open the "modulusui.conf.js" file. Most importantly, you'll want to check these settings:


  • api.baseUrl, the URL of the Modulus server that Modulus UI will connect to
  • appUrl, the URL Modulus UI will be served from
  • auth.authenticateUrl and auth.clientId, parameters used to perform OAuth login with OpenMRS ID
  • auth.clientId must match clients.clientId in modulus-config.groovy

Example file: modulusui.conf.js

Shown below is one that is ready to use – save it to config/modulusui.conf.js

module.exports = {
  // Configuration relating to Modulus Core.
  api: {
    // Base URL of the location where Modulus Core is running. Do not include
    // `/api` in the base URL.
    baseUrl: 'http://localhost:8080',
    // Set to `true` to disable writable actions on the Modulus API, such as
    // uploading releases or editing modules.
    readOnly: false
  // URL where this instance of Modulus UI will be publicly accessible  
  appUrl: 'http://localhost:8083',
  // OAuth Client credentials
  auth: {
    omrsIdBaseUrl: 'http://localhost:3000',
    authenticateUrl: 'http://localhost:8080/login?provider=openmrsid',
    clientId: 'modulus123'

Run Modulus UI

From the terminal, in the openmrs-contrib-modulus-ui directory run

$ grunt serve


Visit the url you set in appUrl.baseURL.

Remember to have Modulus running to serve the back-end otherwise you'll receive this error:

Now you have a fully functional Modulus instance, both front-end and back-end. If you want to load metadata for some modules read on.


Import Modules metadata into local instance

Download this file: Modules_Metadata.sql

In the terminal run:

mysql -u root modulus < [location of file]/Modules_Metadata.sql

This will copy the contents of the downloaded file into the "modulus" database we created earlier.


The end result should look like this:


Modulus on Github

Modulus-UI on Github

Related Pages