Developer Guide

If you are new to the project, a great place to start is Getting Started

Methodology

In order to accelerate project delivery, OpenLMIS version 3 uses a scaled agile approach. Read more about our Methodology and Process.

Development Requirements

Minimum

  • Processor which supports virtualization:  i.e. it must be able to run Docker
  • 16 GB RAM (at least 8GB allocated to Docker)
  • GitHub Account
  • Good 3G internet

Tech Stack

For OpenLMIS version 3, the primary technologies used are:

  • Docker to run micro-services in containers. Using Docker, OpenLMIS can run on Linux, Mac, Windows or in the cloud. 
  • Java 8 with Java Spring for the back-end services. Each micro-service provides a RESTful JSON API over HTTP.
  • JavaScript with AngularJS 1 for a web application that runs in web browsers. Chrome and Firefox are supported.

LayerTool
Browser Application

Javascript with AngularJS 1

(HTML5 and CSS are used for templates and layout)

API ServicesJava 8 with Java Spring
DatabasePostgreSQL 9 or Amazon RDS
Infrastructure

Docker Engine 1 and Docker Compose 1

(Docker Containers run locally, in a data center, or in the cloud)

Skillset

To contribute to OpenLMIS, it will be important to have experience with Java or AngularJS or both. To work on the Java back-end of OpenLMIS, you should have knowledge of Java and an interest in working with the Spring Framework and RESTful APIs. To work on the AngularJS front-end of OpenLMIS, you should have knowledge of Javascript, HTML and CSS and an interest in working with the AngularJS framework. 

If you do not have these tech skills, there are lots of online resources to learn, and there are also lots of ways to contribute to OpenLMIS besides writing code. We value contributions including bug reports, feature suggestions, documentation, translations and more. See the Contributing section on docs.openlmis.org.

Technical Philosophy

The OpenLMIS software is focused on a service-based, API-driven, modular approach designed to better support customizations and extensions. The goal of this micro-services architecture is to enable multiple OpenLMIS implementations in different countries while still sharing one global, open source codebase. The end result is a powerful, flexible product that emphasizes interoperability, extensibility, andperformance at scale across countries, programs, and products.

Infrastructure

(also see Frameworks & Libraries)

Repositories on GitHub (each service/component in its own repo): OpenLMIS

Issue tracking on JIRA.

Developer Forum hosted on Google Groups:  https://groups.google.com/forum/#!forum/openlmis-dev

Jenkins for continuous integration.

SonarQube for static code analysis.

Transifex for translation/localization management.

Slack for real time chat, GitHub notifications, etc.  Slack domain is openlmis.slack.com.

docs.openlmis.org as a global document repository.

An ERD of the dev branch is at ci.openlmis.org/ERD/, built by a Jenkins build job. An ERD for each service is built by Jenkins and published online at URLs that follow this pattern: http://ci.openlmis.org/erd-[name of the service]/ (eg, http://ci.openlmis.org/erd-referencedata/).


Dev Tools

Docker is used for managing containers. See our Docker Cheat Sheet

IntelliJ IDEA is the recommended IDE for Java web service development. See our IntelliJ IDEA Knowledge Base


Coding Standards

See OpenLMIS Coding Standards and Service Style Guide.

For UI, see UI Extension Architecture and GuideUI Coding Conventions and UI Build documentation in the Requisition UI Readme and Dev UI Readme.


Communication

The dev community supports several communication channels.  Each mode serves a different purpose:

  • OpenLMIS Discourse
    • Discussions, questions and decisions on application design and behavior.  As messages are kept forever, this is the place to record the how and why for future reference
    • Discussions and decisions by the Tech Committee (as well as the other OpenLMIS Committees)
    • Technical support questions
    • Announcements, news, etc.
  • Slack
    • For messages that are transient/short-lived.  Good for real-time discussion and project messaging.  No guarantee messages are persisted forever.
    • #dev is reserved for tool notifications.  Humans shouldn't generally post here as it will get lost among automated notifications
    • #general for most OpenLMIS messages
    • #toolbox for tools and techniques relevant to the OpenLMIS' tech stack
    • #random for non-project FYIs, relevant articles and links, etc.
  • JIRA
    • Issue tracking, project management, Epics, Stories, etc.
    • Discussion on specific bugs, stories, etc. should use the Comment facility on the JIRA issues, NOT private emails.
  • Email
    • If an email thread veers to generating discussions/decisions that should be public per a healthy open source project, move it to a community forum.


If you are interested in developing or deploying OpenLMIS, please reach out to the community as soon as possible, and be sure to read the Contribution Guide before getting started. The community will help you understand the current state of the product and how best for you to move forward.

OpenLMIS: the global initiative for powerful LMIS software