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 Google Code-in 2014 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 (id.openmrs.org)

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

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

• OpenMRS ID 

• Redirect URL – will likely be http://localhost:8080/oauth/openmrsid/callback.

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

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

Setting up Modulus Server

Install Grails

Run the following command in your terminal.

Install Grails

Clone the Modulus Repo and Install Submodules

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

Download Modulus Repo

Set up MySQL Database

Using the terminal run:

MySQL Modulus Database creation

-u stands for user called

-e stands for execute this

If you get the error ; 

MySQL Error

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

MySQL Server 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

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

Open

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.

modulus-config.groovy

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: 

modulus-config.groovy

Run Modulus

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

Grails - Modulus

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.

Open

Installing Modulus UI

Clone the Modulus UI Repo.

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

Download Modulus UI Repo

Install Grunt

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

Install Grunt Globally

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

Install Dependencies

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

modulusui.conf.js

Run Modulus UI

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

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:

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