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 (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.
$ 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 $.)
$ 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.
$ sdk install grails 2.3.7
Clone the Modulus Repo and Install Submodules
Navigate to where you want to save the repository and run:
$ git clone https://github.com/openmrs/openmrs-contrib-modulus.git $ cd openmrs-contrib-modulus $ git submodule init $ git submodule update
Set up MySQL Database
Using the terminal run:
$ mysql -u root -e "CREATE DATABASE modulus"
-u stands for user called
-e stands for execute this
If you get the 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:
$ 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:
defaults write com.apple.finder 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.
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:
import org.openmrs.modulus.oauth.OpenMrsIdApi
grails.serverURL = "http://localhost:8080"
modulus {
uploadDestionation = "/tmp/uploads"
openmrsid.hostname = "https://id.openmrs.org"
}
// 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 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:
$ git clone https://github.com/openmrs/openmrs-contrib-modulus-ui.git $ cd openmrs-contrib-modulus-ui
Install Grunt
Using npm* install Grunt. npm stands for Node Package Manager and comes with Node.
$ 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):
$ 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 toappUrl, the URL Modulus UI will be served fromauth.authenticateUrlandauth.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:
Related Pages