Skip to content

Latest commit

 

History

History
141 lines (89 loc) · 4.63 KB

README.md

File metadata and controls

141 lines (89 loc) · 4.63 KB

Project Setup Guide

Welcome to the project! Follow the instructions below to set up the environment and get started.

🛠️ Setup Instructions

Accessing artifacts hosted on GitHub requires a GitHub account for downloading purposes. Please follow these steps:

  1. Duplicate and Rename Configuration File:

    • Copy the file local.properties.default and rename it to local.properties.
    • Open the local.properties file and insert your GitHub account/token details.

  2. Modify Additional Properties:

    • Modify other properties (e.g., URLs, OAuth2) only if you are using a custom OpenMRS or Keycloak setup.

🚀 Running OpenMRS Server & Keycloak

You can run the OpenMRS Server and Keycloak using one of the following options:

Option 1: Using Docker Compose

  1. Use the docker-compose file available in the root of this project.
  2. Create a .env file from the provided template .env.default.

Option 2: Using OpenMRS Distro SSO Project

  1. Follow the steps provided in the OpenMRS Distro SSO repository.
  2. Apply any necessary changes as per your setup.

Keycloak Login

  • To log in using Keycloak, use one of the predefined users listed here.

🔒 Authentication Methods

This project supports the following authentication methods:

  • Basic Auth
  • OAuth2

Update the auth_method property in your configuration to:

  • "basic" for Basic Auth
  • "openid" for OAuth2

🔗 Configuring FHIR Sync URLs

To enable FHIR synchronization, set the fhir_sync_urls property with the required resource URLs in your local.properties file.

Each resource type should be separated by a comma (,).

Example:

fhir_sync_urls=Location?_sort=_lastUpdated&_summary=data,Patient?_sort=_lastUpdated,Encounter?_sort=_lastUpdated,Observation?_sort=_lastUpdated

📧 Configuring the Developer Email for Application Diagnostics

To ensure application diagnostics are sent to the correct developer email upon user request:

  1. Open the local.properties file.
  2. Update the support_email property with the desired email address.

📝 OpenMRS Notes

Logout URL

To log out of the OpenMRS web application:

http://localhost:8080/realms/main/protocol/openid-connect/logout

Note: There is an issue with the current OpenMRS installation and the SSO logout process.

List of Users

A list of predefined users for OpenMRS can be found here:
Keycloak Users CSV

🔧 Common Setup Issues and Fixes

  1. Error 404 on clicking login button:

    • Ensure that the discovery_uri's port matches your Keycloak container's port in the local.properties file.

  2. Error 404 after successful login, and sync is failing:

    • Verify that the BASE_URL's port matches your Gateway container's port in the local.properties file.

  3. First sync is fetching too many resources:

    • Narrow down the scope of the download sync by modifying the fhir_sync_urls property in the local.properties file.

🌐 Keycloak and Hostname Configuration (localhost vs 10.0.0.2)

Keycloak can be accessed through different URLs depending on the use case:

  • localhost is used to log into the OpenMRS web application.
  • 10.0.0.2 is used by the Android app.

To configure this:

  1. Update the KC_HOSTNAME variable in docker-compose.yml (line 89).
  2. After modifying, restart using: docker compose up -d Alternatively to restart only the Keycloak service, you can use: docker compose restart keycloak

🔨 Development Notes

OpenMRS Development

Refer to the custom code created for OpenMRS:
Google Android FHIR OpenMRS Code

Android FHIR SDK with the FHIR Info Gateway

Create a release

To initiate the build workflow:

  • From Git: Just create and push a tag vX.Y.Z
  • From Web UI: Create a release and the related tag vX.Y.Z and Delete immediately the Realse

the Build action should be triggered and it will create a new release containing the apk configured to use dev3.openmrs.org as the OpenMRS Backend.