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 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: 

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 0.29.0 $ 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 v5.11.0

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

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

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.