This application serves as an index of add-ons for the OpenMRS Platform.
We support:
- OpenMRS Modules (OMOD files)
- Open Web Apps (OWA files).
This replaces Modulus where we hosted and published modules. The aim of this project is different -- we want people to host their OpenMRS add-ons elsewhere (bintray, github releases, etc) and we will merely index them for easy searching, in one unified index.
For convenience we'll also support indexing modules that have already been published to OpenMRS's maven repository.
See PUBLISHING-AN-ADD-ON.
The server is a Spring Boot application, written with Java 8, built using maven. The web UI is a ReactJS SPA, built with npm (using webpack).
It uses ElasticSearch to store its index.
We use OpenMRS's Bamboo CI server to continuously build this application.
To build locally, you need to build the web UI first, and then run the server. (Though if you skip building the web UI you'll still be able to see the server's REST API)
You must have NodeJS and NPM installed already.
From src/main/ui do
> npm ci
> npm run build:dev
CI does npm run build:prod which minimizes js/css.
You need to be running ElasticSearch to run this application. To run this using Docker, do:
> mkdir esdata
> docker run --name es-addons -p 9200:9200 -p 9300:9300 -v "${PWD}/esdata:/usr/share/elasticsearch/data" -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:7.11.0
If you aren't running ElasticSearch on http://localhost:9200 then you'll need to set spring.elasticsearch.jest.uris in
your custom application config. (See below for how to set this configuration.)
You must have Java 11.
IntelliJ IDEA has nice support for Spring Boot: you can create a Run Configuration for the Application class.
To run at the command line (from the root of this project, where pom.xml is):
> mvn clean package
> // to run integration tests: mvn clean verify
> java -jar target/addonindex-*.jar
Then navigate to http://localhost:8080/
We include spring-boot-devtools in this project, so any changes on the classpath are automatically deployed to the
running application, and it is restarted if necessary. (In IntelliJ you would trigger this with the Build Project
command, which is Command-F9 on OSX.)
Thus, the workflow of doing front-end development is:
- (First, run the application in IntelliJ)
- Make changes to the javascript code
- (in
src/main/ui)npm run build:dev(set up an IDE Run Configuration for this) - In IntelliJ,
Build Project - Refresh your browser window
To override the default settings, create a file config/application.yml whose contents should be like our
application.yml in this source code. For development you might want to create
this file with contents:
logging.level:
org.openmrs.addonindex: DEBUG
This application is bandwidth-heavy on its first run (e.g. it downloads all OMOD versions to inspect their configuration). If you want to save bandwidth, set this in your custom config (though this will lose some functionality, like being able to fetch modules by their package):
scheduler:
fetch_details_to_index:
fetch_extra_details: false
In order to deploy this to OpenMRS staging infrastructure, we package this application as a docker container and publish it
to dockerhub as openmrs/addonindex. You would do this manually as
mvn package spring-build:build-image
but CI builds it automatically, so you don't need to do this.
The production server is updated via a webhook whenever you push to the production tag on dockerhub.
This is automated in CI as a manual stage in the build plan. In case you need to do this manually, first you need to have a docker image to tag, which you do either by:
- (Option A) build everything locally (first the UI then the jar + docker build, and looking for output like
Successfully built 089a664e4a61) - (Option B) do
docker pull <id>
Then you need to tag this and push to dockerhub, like:
docker tag <id> openmrs/addonindex:production
docker push openmrs/addonindex:production
See CONTRIBUTING.md.