This guide is intended to guide new or existing Maintainers on how to maintain the openIMIS project. It contains lots of links/cross-references to documentation that was already created in Confluence but tries to put it all in one place for ease of reference.

All of the documentation here pertains to the openIMIS modular architecture. Documentation on legacy openIMIS development and maintenance may be found in pages on Confluence.

Platforms

GitHub - Source Control and GitHub Packages/Container Registry
Lokalise Translation Management platform - openIMIS - openIMIS Wiki
TestLink - Performing and managing QA and User Acceptance Tests
Docker - Building and running images for deployment/implementations
Discord - Community engagement and communication
Jira - product planning and issue tracking
Service Desk - user support
Other platforms (Communication Platforms - openIMIS - openIMIS Wiki)

Access to GitHub

Most contributors will have to fork the openIMIS repos and open Pull Requests. However, maintenance teams that are authorized to the openIMIS GitHub org will be granted access to create branches and PRs directly on the repos.

Teams are managed in a hierarchical manner. The core maintenance team creates and assigns teams. There are two high-level teams on the org, the main team is product-team. All development/maintentenance teams are created as child teams under the main product-team. Further more, there are teams for Developers and Students - there is also a hierarchy for the teams under these.

GitHub Workflow

Please go through the flow here to understand the main development/release flow:

https://openimis.atlassian.net/wiki/spaces/OP/pages/619380737

Cloning the openIMIS repositories

There is a repository with tools/scripts to help Developers to onboard and manage their openIMIS development environment. The repository is named openimis-dev-tools:

GitHub - openimis/openimis-dev-tools: This repository group tools for developers to initialize and develop the openIMIS system.

It is recommended to use this repository as a starting point as it will ease the process of dealing with the many(!) repositories that make up the project. The devtools use Python 3 for automating some processes. Make sure you have Python installed and accessible on your PATH.

Cloning the backend and frontend modules using the openimis-dev-tools

Clone the repository and navigate to it in your terminal

$ git clone --recurse-submodules https://github.com/openimis/openimis-dev-tools.git

$ cd openimis-dev-tools

Run the setup-local-dev.py script to clone all backend and frontend repos

$ python3 ./python/setup-local-dev.py

This will attempt to download several repositories from openIMIS organisation on GitHub to your local machine. This may take some time and will require patience since GitHub will apply rate-limits to the process as we are downloading a lot of repos.

Once this is complete, you should have two new directories,

backend-packages - this directory should have repositories for the Python backend modules
frontend-packages - this directory should have repositories for the React frontend module

Customizing the branch of the cloned repositories

The repositories cloned using the step above default to checking out to the develop branch. If you would like to checkout to any other branch, for example main. You will have to edit the python/config.py file in the openimis-dev-tools before running the scripts.

Running the backend from cloned repositories

If you have followed the instructions above, you will have a backend directory in the openimis-dev-tools repo. You can run the backend from this directory.
These instructions are adapted from openimis-be_py/README.md at develop · openimis/openimis-be_py

Within the backend directory

First, install openIMIS (external) dependencies: pip install -r requirements.txt.
Install development requirements pip install -r dev-requirements.txt
Generate the openIMIS modules dependencies file (from openimis.json config):
- python3 script/modules-requirements.py openimis.json > modules-requirements.txt
- install openIMIS current modules: pip install -r modules-requirements.txt
Copy the example environment setup and adjust the settings (like database connection):
- cp .env.example .env.
start openIMIS from within backend/openIMIS:
- python manage.py runserver

Running the frontend from cloned repositories

If you have followed the instructions above, you will have a frontend directory in the openimis-dev-tools repo. You can run the frontend from this directory.

These instructions are adapted from: GitHub - openimis/openimis-fe_js: The openIMIS component assembling all frontend modules

Within the frontend directory

generate the openIMIS modules dependencies and locales (from openimis.json config):
- yarn load-config openimis.json
clean yarn cache in case local directory / git /link are used: yarn cache clean
install openIMIS technical dependencies: yarn install
install openIMIS technical dependencies: yarn start
- This should start a webserver port 3000 and accessible on http://localhost:3000/front
To build openIMIS frontend (in development mode): yarn build

Cloning more modules or adding new modules

These steps above only clone/setup the default project modules based on what is configured in the openimis-dev-tools repo. However, if there are other modules introduced or you are working on a new module, we recommend you clone or create the repositories into either of these directories (backend-packages or frontend-packages) so that all you work is in one place.

Setting Up the Database

Database Migrations

The project uses Django migrations for migrations. Django migrations should have dependencies specified where necessary

NOTE: Check that migrations are created ahead of the release

PULLING Changes for the cloned repositories

Assuming you’re on a Linux or MacOS you can run the following command to pull changes inside the openimis-dev-tools directory.

The following script will pull changes for the backend and frontend assemblies, and perform a git pull for all sub-repositories in the backend-packages and frontend-packages directories :-

#!/bin/sh
# You can place this in a file like pull-openimis.sh

# You will first have to be in the dev tools directory, so don't forget to: 
# cd openimis-dev-tools 
git pull --all

# Pull changes for the backend assembly
cd backend && git pull --all

# Pull changes for the frontend assembly
cd frontend && git pull --all

# Pull changes for repos in backend-packages
for dir in backend-packages/*; do
  if [ -d "$dir/.git" ]; then
    echo "Updating $dir..."
    (cd "$dir" && git pull --all)
  fi
done
# Pull changes for repos in backend-packages
for dir in frontend-packages/*; do
  if [ -d "$dir/.git" ]; then
    echo "Updating $dir..."
    (cd "$dir" && git pull --all)
  fi
done

The importance of `openimis.json`

The openimis.json is one of the crucial files in the project or development of openIMIS. This file is used in various workflows to build or package a complete solution. The openimis.json contains links to modules that should be included into a built or running openIMIS solution. This file enables developers and implementers to extend or limit the functionality of the openIMIS solution, especially the modular architecture.

Issue Tracking

The issue tracking process is documented here: https://openimis.atlassian.net/wiki/spaces/OP/pages/40665170

Checking the Open Pull Requests

The following link gives the Pull Requests that are Open across the whole organisation:

https://github.com/pulls?q=is%3Apr+is%3Aopen+-is%3Adraft+org%3Aopenimis+NOT+%22Bump%22+in%3Atitle+

You will refer to this list to figure out work to review, test and triage.

Working on new or existing modules

The following documentation outlines steps for creating new modules and working on existing modules: https://openimis.atlassian.net/wiki/spaces/OP/pages/4452581399

CI / CD Process

The openIMIS project has Continuous Integration (CI) and Continuous Deployment (CD) setup to using GitHub Actions to ensure that the solution and project is up-to-date and the main develop branch is in a deployable state.

The following gives overview of the CI / CD setup.

Continuous Integration via GitHub actions

It is important to note that each workflow depends on an openimis.json to determine which modules to build/package during the workflow.

ci_assembly.yml workflow in the openimis-be_py repository is the “main” CI workflow
- Installs dependencies
- Runs database migrations
- Runs Django tests --keepdb flag specified to prevent running migrations for all the tests (800 - 900 backend tests)
The ci_module.yaml - acts as a base configuration for CI for sub-modules/repositories
- Workflows in module repositories extend this workflow, see example below
docker.yml is used to build Docker images which are used in nightly builds.
docker-manual.yml - is a workflow that publishes Docker images to the GitHub Container registry. it provides an option to specify a custom openimis.json file. By default it uses the openimis.json in the repo.

Continuous Deployment via GitHub Container Registry and nightly Docker builds

The CD pipeline of the project create a development or testing release of the openIMIS project that is deployed on the develop.openimis.org server. This process depends on the completion of the docker.yml CI workflow, above, and CRON jobs on the server to deploy latest images of the project.

Release Management Process Overview

The release management process is well documented in the wiki. This section is intended to provide guide to these pages. We strongly recommend reading the linked pages.

Start here to understand the release cycle, process and timelines: https://openimis.atlassian.net/wiki/spaces/OP/pages/1322221610
Performing a release requires following a standard Checklist.
Example of a Checklist for a previous release is here: https://openimis.atlassian.net/wiki/spaces/OP/pages/4216422473

The checklist refers to scripts to be run which can be found in the openimis-dev-tools:

screenshot of scripts that aid in release process from the openimis-dev-tools repo

In order for the scripts to work, the python/config.py needs to be configured with a valid GitHub token with enough permissions to create branches on the repositories in the openimis organization.

How to: Create the release branch using the openimis-dev-tools

The following steps outline the release process, as at the time of writing (16th Sep. 2025):

Create a GitHub access token that will be configured to make changes to the repositories, recommended to create a Classic token
Within the openimis-dev-tools:, edit the file in python/config.py with the following changes
1. set GH_TOKEN variable with your token
2. set USER_NAME to your github username
3. set RELEASE_NAME to the name of the release we want to create, e.g. release/25.10
4. NOTE: It is important to note that you MUST not commit this file with your token in it at any point. (recommendation: read the token from an environment variable)
Within the openimis-dev-tools: Run python3 python/gh-create-release-branch.py
This script will iterate through appropriate the GitHub repositories and create a new branch with the name specified in step 2.c
Within the openimis-dev-tools: Once the branches have been created, run the following to verify/check the release: python3 python/gh-check-release-branch.py

Creating updated openims.json files

Run the (gh-make-release-openimis-json.py) to create updated openimis.json files for both the frontend and backend assemblies. Load result in the appropriate repository.

TODO: screenshots

Creating the release Docker Images

Once all relevant PRs have been merged for the different repositories

Building Images Using GitHub Workflows (Tag-Based Approach)

To build Docker images, you can do so via GitHub Actions by pushing a Git tag. The openIMIS repositories are configured with GitHub workflows that automatically build and publish images when:

A tag is pushed (e.g., 24.10, 25.04)
A pull request is merged to a tracked branch (like develop or main)

Steps to trigger image builds via GitHub:

Make your changes and commit them to the appropriate repo (e.g., openimis-be, openimis-fe, or openimis-pgsql).
Create and push a new Git tag:
git tag 25.10 git push origin 25.10
GitHub Actions will automatically run the workflow, build the Docker image, and publish it to the GitHub Container Registry (GHCR) under the tagged version.

Once the image is published, update your .env file in the openimis-dist_dkr directory with the tag:

BE_TAG=25.10
FE_TAG=25.10
DB_TAG=25.10

Then run:

docker compose pull
docker compose up -d

This ensures you're using your newly built, tagged images across all services.

You can do this also on the GitHub level. Here there are more details how to deal with that: https://openimis.atlassian.net/wiki/spaces/OP/pages/4452778000

Running the release on the server

Once you have created the docker images above, you can now proceed to logon to the server to perform the release. The release is based on the docker images.

$ cd ./release
$ vim .env
# Updated BE_TAG and FE_TAG values to use the tag of the docker images
$ docker compose pull && docker compose up -d --remove-orphans

Sometimes you may need to clean the Redis cache

$ docker compose exec redis redis-cli -a redisUserPass FLUSHALL

Infrastructure

Services Running on Servers

The openIMIS project hosts several services on servers for demo, solution building and testing releases among other things. This section gives an overview of the physical and logical setup of these services. Refer the the sub-pages for more information:

Server Landscape : Server Landscape - openIMIS - openIMIS Wiki
DNS Management information: https://openimis.atlassian.net/wiki/spaces/OP/pages/3316285449

Server S1	Server S2

Server S1	Server S2
@Patrick Delcroix @Dragos Dobre could you please add all the name of all web services that we have in S1 and S2

Maintainer Guide

Platforms

Access to GitHub

GitHub Workflow

Cloning the openIMIS repositories

Cloning the backend and frontend modules using the openimis-dev-tools

Customizing the branch of the cloned repositories

Running the backend from cloned repositories

Running the frontend from cloned repositories

Cloning more modules or adding new modules

Setting Up the Database

Database Migrations

PULLING Changes for the cloned repositories

The importance of `openimis.json`

Issue Tracking

Checking the Open Pull Requests

Working on new or existing modules

CI / CD Process

Continuous Integration via GitHub actions

Continuous Deployment via GitHub Container Registry and nightly Docker builds

Further reading

Release Management Process Overview

How to: Create the release branch using the openimis-dev-tools

Creating updated openims.json files

Creating the release Docker Images

Building Images Using GitHub Workflows (Tag-Based Approach)

Running the release on the server

Infrastructure

Services Running on Servers

Did you encounter a problem or do you have a suggestion?

Please contact our Service Desk

Maintainer Guide

Platforms

Access to GitHub

GitHub Workflow

Cloning the openIMIS repositories

Cloning the backend and frontend modules using the openimis-dev-tools

Customizing the branch of the cloned repositories

Running the backend from cloned repositories

Running the frontend from cloned repositories

Cloning more modules or adding new modules

Setting Up the Database

Database Migrations

PULLING Changes for the cloned repositories

The importance of openimis.json

Issue Tracking

Checking the Open Pull Requests

Working on new or existing modules

CI / CD Process

Continuous Integration via GitHub actions

Continuous Deployment via GitHub Container Registry and nightly Docker builds

Further reading

Release Management Process Overview

How to: Create the release branch using the openimis-dev-tools

Creating updated openims.json files

Creating the release Docker Images

Building Images Using GitHub Workflows (Tag-Based Approach)

Running the release on the server

Infrastructure

Services Running on Servers

Did you encounter a problem or do you have a suggestion?

Please contact our Service Desk

The importance of `openimis.json`