How to install Modulus and Modulus UI
Table of Contents
- 1 Get required credentials for OpenMRS ID
- 2 Install Required Software
- 3 Setting up Modulus Server
- 3.1 Install Grails
- 3.1.1 Install Grails
- 3.2 Clone the Modulus Repo and Install Submodules
- 3.2.1 Download Modulus Repo
- 3.3 Set up MySQL Database
- 3.3.1 MySQL Modulus Database creation
- 3.3.2 MySQL Error
- 3.3.3 MySQL Server Start
- 3.4 Create the modulus-config.groovy file
- 3.4.1 Show hidden folders
- 3.4.2 modulus-config.groovy
- 3.5 Run Modulus
- 3.5.1 Grails - Modulus
- 3.1 Install Grails
- 4 Logging in to OpenMRS on your local instance
- 5 Installing Modulus UI
- 5.1.1.1 Download Modulus UI Repo
- 5.1.2 Install Grunt
- 5.1.2.1 Install Grunt Globally
- 5.1.2.2 Install Dependencies
- 5.1.3 Configure modulusui.conf.js
- 5.1.3.1 modulusui.conf.js
- 5.1.4 Run Modulus UI
- 5.1.5 Import Modules metadata into local instance
- 5.2 Related Pages
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.
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.