Recommended Development Workflow for Teams Customizing Bahmni from Source

Software Bahmni
1

Hi Bahmni Community,

I am working on a custom Bahmni/OpenMRS deployment and have been facing several dependency and compatibility issues while building and running the stack from source.

My goal is to understand the recommended long-term approach for teams that want more control over the platform.

Is it considered a supported/recommended approach to:

  • Build Bahmni modules from source

  • Maintain our own Docker images for OpenMRS, Bahmni Apps, and related services

  • Manage OpenMRS module versions ourselves

  • Maintain a custom deployment pipeline and release process

Or is the expectation that teams should primarily use the official/prebuilt Bahmni images and customize configuration on top of those images?

For teams running production deployments with custom development, what is the common practice in the community?

I would appreciate guidance on:

  1. Recommended architecture for custom deployments.

  2. How much ownership teams typically take over OpenMRS/Bahmni module builds.

  3. Best practices for maintaining custom Docker images while staying compatible with Bahmni releases.

Thanks.

2

I am in the process of figuring out something like this as well, though at our location we don’t want to build the whole of Bahmni + OpenMRS, just the minimal of what we need for some things we have customized.

As far as I can tell, it should be fully possible to maintain your own build system and/or fork the code, but I think a lot of things will be up to you to figure out. I’m sure there are people who can help, but what is supported is probably using the pre-built images.

So far for us, we are building/maintaining our own versions of:

  • a few custom opemrs modules (which interact with the frontend over REST api)
  • bahmniapps with some customization (the Bahmni frontend)
  • bahmni_config (Bahmni frontend configuration)
  • concept dictionary (just some additions on top of the stock dictionary from Bahmni from several years ago)
  • our own build of some of the services, especially pacs-integration, in order to integrate with our x-ray system and process

I’m in the process of setting up the Docker version of Bahmni, and trying to integrating some of these changes in a way to make it as easy as possible to maintain them and pull in upstream changes. I expect that our updates from upstream will be rare (every few years), and I anticipate each time it will take some effort to see what has changed from upstream and merge code and config changes.

One thing about using Docker that I’ve found helpful is being able to replace the image: lines in the compose file with things like build: ./openmrs. Then in a “openmrs” folder, have a Dockerfile which references the Bahmni image (ie FROM bahmni/openmrs:1.1.2) and then applies patches or layers some of my own things on top of it.

An alternative is to clone the git repos, run a build process to make your own Docker images, and then possibly push them to your own docker registry.

Sometimes it takes some effort to figure out what versions of docker images correspond to each other and to different tags or commits in git repos. For example the current bahmni-standard version references:

And these I think correspond to:

It’s not too hard to figure this out, but I don’t know how it would be if you were trying to automate the process.

3

To give you better guidance, could you clarify which of these best describes your use case?

  1. Using Bahmni as-is with configuration customizations (forms, dashboards, reports)
  2. Extending Bahmni with custom modules while keeping the core stack
  3. Building your own product on top of Bahmni with full control over builds and releases
  4. Using only specific Bahmni components (e.g., just OpenMRS + Bahmni Apps)
  5. Also — is this for a single facility or a multi-site deployment?

Based on existing Bahmni community documentation, here are the key recommendations:

General Recommendations

1. Start with Official Docker Images + Config Customization

The documented approach is to use official Bahmni Docker images and build your own config image on top. This keeps you on the upgrade path.

2. Use the Standard Config Repo as a Starting Point

Fork standard-config or clinic-config for your implementation-specific forms, dashboards, reports, and app.json overrides.

3. Use Docker Compose Profiles

The bahmni-docker setup supports profiles — only run the services you need (e.g., skip OpenELIS or Odoo if not required).

4. For Production, Use Docker Swarm (or Similar)

The Docker Swarm guide provides a production-ready reference with replicas, placement constraints, and secrets management.

5. Engage with the Community

6. If Building from Source

  • Fork openmrs-distro-bahmni to control module versions

  • Pin versions and test against Bahmni’s release notes before upgrading modules independently

  • Publish custom images to your own registry

7. Avoid Unnecessary Forking of Core Code

Prefer config-level customization, Groovy extensions, or custom OpenMRS modules over forking Bahmni’s core repos. This significantly reduces the maintenance burden during upgrades.

Key message: The community strongly favors a “configure, don’t fork” philosophy. The more you stay aligned with upstream Bahmni, the easier upgrades and community support will be. Only take on source-level ownership when you have a clear need and the engineering capacity to maintain it long-term.