| api/ |
Java and resource files for building the java api jar file. |
| tools/ |
Meta code used during compiling and testing. Does not go into any released binary (like doclets). |
| web/ |
Java and resource files that are used in the webapp/war file. |
| webapp/ |
files used in building the war file (contains JSP files on older versions). |
| pom.xml |
The main maven file used to build and package OpenMRS. |
## Software Development Kit
For rapid development of modules and the OpenMRS Platform code, see the
[OpenMRS SDK documentation](https://wiki.openmrs.org/display/docs/OpenMRS+SDK).
## Extending OpenMRS with Modules
OpenMRS has a modular architecture that allows developers to extend the OpenMRS core functionality by creating modules that can easily be added or removed to meet the needs of a specific implementation.
Before creating your own module, go to the [OpenMRS Module Repository](https://addons.openmrs.org/) and see if there is already a module for your specific use case. If so, deploy and try it. If functionality is missing, work with the module's developers to add the feature.
If you haven't found what you were looking for, refer to the [Module - wiki](https://wiki.openmrs.org/display/docs/Modules) to learn how you can create a new module.
## Documentation
### Developer guides
If you want to contribute please refer to these resources
* [Getting Started as a Developer](https://openmrs.atlassian.net/wiki/spaces/docs/pages/25477022/Getting+Started+as+a+Developer)
* [How To Configure Your IDE](https://openmrs.atlassian.net/wiki/spaces/Archives/pages/25506949/How-To+Setup+And+Use+Your+IDE)
* [How To Make a Pull Request](https://wiki.openmrs.org/display/docs/Pull+Request+Tips)
### Wiki
If you are looking for detailed guides on how to install, configure, contribute and
extend OpenMRS, visit [the OpenMRS Wiki](https://wiki.openmrs.org).
### Website
For more information about OpenMRS as an organization, check
[the OpenMRS website](https://openmrs.org).
## Contributing
Contributions are very welcome. We can definitely use your help!
OpenMRS organizes the privileges of its contributors in developer stages which
are documented [here](https://wiki.openmrs.org/display/RES/OpenMRS+Developer+Stages).
Read the following sections to find out where you could help.
### Code
Check out our [contributing guidelines](CONTRIBUTING.md), read through the [Developer guides](#developer-guides).
After you've read up :eyeglasses: [grab an introductory issue](https://openmrs.atlassian.net/wiki/x/a8GEAQ) that is `Ready For Work`.
### Code Reviews
If you do not have time to develop but have experience with OpenMRS or reviewing
code, your help with code reviews would be greatly appreciated!
Read [the code review guide](https://openmrs.atlassian.net/wiki/x/-r_EAQ) and get started reviewing pull requests!
### Translation
We use [Transifex](https://explore.transifex.com/openmrs/OpenMRS/) to manage our translations.
The `messages.properties` file in this repository is our single source of
truth. It contains key, value pairs for the English language which is the
default.
Transifex fetches updates to this file every night so they can be translated
on the Transifex website. At any time, we can pull new translations from Transifex
back into this repository. Other languages, such as Spanish, will then be in
the `messages_es.properties` file.
If you would like to know how to help with translations, see
[the OpenMRS translation guide](https://om.rs/translate).
### Dependency Updates
Dependabot raises dependency update PRs against `master` and each maintained release branch. It only reads
[`.github/dependabot.yml`](.github/dependabot.yml) from `master`, so when a release branch is cut or reaches end
of life, its entries in that file need to be added or removed.
## Issues
If you want to help fix existing issues or have found a bug to report, please go to
[the OpenMRS issue tracker](https://issues.openmrs.org).
## Community
[](https://talk.openmrs.org)
[](https://slack.openmrs.org/)
[](https://wiki.openmrs.org)
## Support
Talk to us on [OpenMRS Talk](https://talk.openmrs.org/)
## License
[MPL 2.0 w/ HD](LICENSE) © [OpenMRS Inc.](https://openmrs.org/)
[](https://github.com/openmrs/openmrs-core/actions/workflows/build.yaml) [](https://app.codecov.io/gh/openmrs/openmrs-core) [](https://sonarcloud.io/summary/new_code?id=openmrs_openmrs-core)
api: [](https://snyk.io/test/github/openmrs/openmrs-core?targetFile=api%2Fpom.xml)
test: [](https://snyk.io/test/github/openmrs/openmrs-core?targetFile=test%2Fpom.xml)
tools: [](https://snyk.io/test/github/openmrs/openmrs-core?targetFile=tools%2Fpom.xml)
web: [](https://snyk.io/test/github/openmrs/openmrs-core?targetFile=web%2Fpom.xml)
webapp: [](https://snyk.io/test/github/openmrs/openmrs-core?targetFile=webapp%2Fpom.xml)
DPGA: [](https://digitalpublicgoods.net/r/openmrs)
OpenMRS is a patient-based medical record system focusing on giving providers a free customizable electronic medical record system (EMR).
The mission of OpenMRS is to improve health care delivery in resource-constrained environments by coordinating a global community that creates a robust, scalable, user-driven, open source medical record system platform.
#### Table of Contents
1. [Build](#build)
1. [Prerequisites](#prerequisites)
2. [Build Command](#build-command)
3. [Deploy](#deploy)
2. [Docker build](#docker-build)
3. [Navigating the repository](#navigating-the-repository)
4. [Software Development Kit](#software-development-kit)
5. [Extending OpenMRS with Modules](#extending-openmrs-with-modules)
6. [Documentation](#documentation)
1. [Developer guides](#developer-guides)
2. [Wiki](#wiki)
3. [Website](#website)
7. [Contributing](#contributing)
1. [Code](#code)
2. [Code Reviews](#code-reviews)
3. [Translation](#translation)
4. [Dependency Updates](#dependency-updates)
8. [Issues](#issues)
9. [Community](#community)
10. [Support](#support)
11. [License](#license)
## Build
### Prerequisites
#### Java
OpenMRS is a Java application which is why you need to install a Java JDK.
If you want to build the master branch you will need a Java JDK of minimum version 8.
#### Maven
Install the build tool [Maven](https://maven.apache.org/).
You need to ensure that Maven uses the Java JDK needed for the branch you want to build.
To do so execute
```bash
mvn -version
```
which will tell you what version Maven is using. Refer to the [Maven docs](https://maven.apache.org/configure.html) if you need to configure Maven.
#### Git
Install the version control tool [git](https://git-scm.com/) and clone this repository with
```bash
git clone https://github.com/openmrs/openmrs-core.git
```
### Build Command
After you have taken care of the [Prerequisites](#prerequisites)
Execute the following
```bash
cd openmrs-core
./mvnw clean package
```
This will generate the OpenMRS application in `webapp/target/openmrs.war`, which you will have to deploy to an application server such as [Tomcat](https://tomcat.apache.org/) or [Jetty](https://jetty.org/).
### Deploy
For development purposes you can simply deploy the `openmrs.war` into the application server jetty via
```bash
cd openmrs-core/webapp
../mvnw jetty:run
```
To run Jetty on a custom port, use the `jetty.http.port` property:
```bash
../mvnw -Djetty.http.port=8081 jetty:run
```
To run on Cargo, use the `cargo:run` command:
```bash
../mvnw cargo:run
```
To run Cargo on a custom port, use the `cargo.servlet.port` property:
```bash
../mvnw -Dcargo.servlet.port=8081 cargo:run
```
If all goes well (check the console output) you can access the OpenMRS application at `localhost:8080/openmrs`.
Refer to [Getting Started as a Developer](https://wiki.openmrs.org/display/docs/Getting+Started+as+a+Developer) for some more information
on useful Maven commands and build options.
## Docker build
Docker builds are still a work in progress. We appreciate any feedback and improvements to the process.
The only prerequisite needed is Docker.
In order to build a development version run:
```bash
docker compose build
```
It calls `mvn install` by default. If you would like to customize mvn build arguments you can do so by running:
```bash
docker compose build --build-arg MVN_ARGS='install -DskipTests'
```
It is also possible to use the built dev image to run jetty:
```bash
docker compose up
```
In order to build a production version run:
```bash
docker compose -f docker-compose.yml build
```
It first builds the dev image and then an image with Tomcat and openmrs.war.
It has no dev dependencies.
The production version can be run with:
```bash
docker compose -f docker-compose.yml up
```
If you want to debug, you need to run a development version and connect your debugger to port 8000, which is exposed by default.
Unfortunately, at this point any code changes require full restart and rebuild of the docker container. To speed up the process,
please use:
```bash
docker compose build --build-arg MVN_ARGS='install -DskipTests'
docker compose up
```
We are working towards providing support for Spring Boot auto-reload feature, which will be documented here once ready.
It is also possible to deploy an image built by our CI, which is published at
[OpenMRS Core on Docker Hub](https://hub.docker.com/r/openmrs/openmrs-core).
You can run any tag available with:
```bash
TAG=nightly docker compose -f docker-compose.yml up
```
It is also possible to run a development version of an image with:
```bash
TAG=dev docker compose up
```
All development versions contain dev suffix. The cache suffix is for use by our CI.
### Running with ElasticSearch
OpenMRS can run with ElasticSearch backend instead of the in-built Lucene index. You can run it with:
```bash
docker compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.es.yml up
```
If you change backend, you need to rebuild the search index by going to Legacy UI -> Administration -> Search Index. Alternatively, you can rebuild the search index using the `searchindexupdate` REST endpoint.
### Running with Grafana
OpenMRS can run with Grafana for monitoring logs. You can run it with:
```bash
docker compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.grafana.yml up
```
Grafana will be available at http://localhost:3000. Use admin as username and see docker-compose.grafana.yml for the initial password.
### Scheduler Dashboard
The scheduler dashboard can be accessed at http://localhost:9000 by default (user: admin / password: Admin123). It is enabled by default when running `docker compose up` command. It is configured in `docker-compose.override.yml`.
If you want to enable it in other environments, you need to set the following properties in `openmrs-runtime.properties`:
```bash
jobrunr.dashboard.enabled=true
jobrunr.dashboard.password=someStrongPassword
```
## Navigating the repository
The project tree is set up as follows: