Upgrading Bahmni on CentOS to Bahmni Standard (or Lite) on Docker
If you are new to Bahmni on Docker, we recommend you to go through the Getting Started documentation to try Bahmni with demo database on docker and get used to different configurations and commands before starting the migration.
[Dec-2023] The Bahmni team has conducted an online training on migrating from Bahmni CentOS, to Dockerized version of Bahmni. Please see the training material with video recordings here: Migrating Bahmni from CentOS to Docker (Training)
This migration guide is in its initial stages. We recommend following the below instructions to setup a pre-prod / test environment first and test if all of the critical flows are working fine and then move to production. Make sure you have proper backup from your existing installation. This process has been conducted in two locations till now. Please let us know any feedback or improvements to this process, if you try it out.
Preparing for upgrade:
When planning of upgrade from a existing production system on CentOS to running Bahmni on Docker, plan for additional hardware (servers) which will help you run Bahmni docker. A decent server for a production environment running most of standard components should be one with 4CPUs running with CPU > 3GHz and 16 GB of RAM.
Backing up artifacts:
Below are the common backup artifacts to be extracted from an existing Bahmni installation covering all components of Bahmni. If you are not using any component listed below you can ignore the backup artifacts related to it.
Artifact Name | Description | Default location on server | Command to generate the artifact with default credentials | |
---|---|---|---|---|
1 | Bahmni Configuration | The configuration folder of Bahmni and its sub-components. Most implementations would have this as a Git repository. | /opt/bahmni-web/etc/bahmni_config/ |
|
2 | OpenMRS Database Backup | Backup of the OpenMRS mysql database | - |
|
3 | Reports Database Backup | Backup of the Reports mysql database | - |
|
4 | OpenELIS Database Backup | Backup of the OpenELIS Postgres database | - |
|
5 | Odoo Database Backup | Backup of the Odoo Postgres database | - |
|
6 | DCM4CHEE Database Backup | Backup of the DCM4CHEE Postgres database | - |
|
7 | Pacs Integration Database Backup | Backup of the PACS Integration Postgres database | - |
|
8 | Patient Images | Patient Photos captured from the registration page of Bahmni | /home/bahmni/patient_images |
|
9 | Document Images | Documents uploaded for a patient from multiple modules like Patient Documents module, Form observations etc | /home/bahmni/document_images |
|
10 | Uploaded Results | Documents that are uploaded from OpenELIS during test result upload | /home/bahmni/uploaded_results |
|
11 | Uploaded Files | Files that are uploaded from Admin Module of Bahmni | /home/bahmni/uploaded-files |
|
12 | Clinical Forms JSON Files | The JSON files that are created by form builder module when defining form2 forms. Applicable only when Form-2 forms are used | /home/bahmni/clinical_forms |
|
13 | DCM4CHEE Dicom Files | The dicom files captured and stored in the dcm4chee server archive | /home/bahmni/pacs_images/archive |
|
14 | Bahmni Queued Reports Results Files | The result files of reports added to queue from the reports module | /home/bahmni/reports |
|
Once you have gathered all the artifacts you would have directory structure as below. You can validate by running ls -al /bahmni-backup
. Also validate whether backups are properly take by doing head -n 100
of db backup .sql files and doing an ls
of other file directories.
Now you can compress the backup artifacts folder /bahmni-backup
using zip or gzip and copy it to the new server over an external Hard drive or USB stick.
Setting up the new server:
Follow the pre-requisites in the Getting started on Docker page to install the required tools. It would be mostly on installing docker, docker compose and git, and then cloning the bahmni-docker repository.
Copying in the backup artifacts from your old implementation. Move the backup artifacts same as directory structure mentioned above in the new server and unzip if required. Also make a note of the path where you have copied the backup artifacts.
Using your implementation specific configuration:
In general we recommend implementations to track changes in their implementation specific configuration files using a version control tool like Git. This would be helpful to track what changes have been made, when and by whom. Follow the steps in this documentation to know how you can use your implementation specific configuration with docker. Note: Only update the paths or config image variables, don't start services by running docker compose up -d
.
This is an important step towards migration and make sure you followed the steps as in the referred document above.
Updating variables in environment configuration file:
The .env files present in bahmni-docker/bahmni-standard folder contains all configurable properties for running Bahmni on Docker. You can choose to use either .env or .env.dev. The .env file will soon have specific image tags for a released version and .env.dev will have latest image tags pointing to images built from mainline code of all repositories.
Some of the variables related to database configuration needs to be updated in the .env file as the default setup comes with demo database images. Update the variable values as mentioned in below table
Variable Name | Value to be updated | |
---|---|---|
1 |
| The time zone where your previous instance was running. Example: |
2 |
| mysql:8.0 |
3 |
| postgres:9.6 |
4 |
| postgres:9.6 |
5 |
| postgres:16.1 |
6 |
| clinlims |
7 |
| clinlims |
8 |
| clinlims |
Restoring Bahmni Application and Databases:
Running the Restore Script:
Before executing the restore script, if you are planning to use a different env file other than .env
open the bahmni-docker/bahmni-standard/restore_bahmni_standard.sh
file and update the value of BAHMNI_DOCKER_ENV_FILE
variable in the script.
Now cd into the bahmni-docker/bahmni-standard
directory and run the restore script by using the following command
./restore_bahmni_standard.sh <restore-artifacts-folder-path>
Example: ./restore_bahmni_standard.sh /bahmni-backup --> Assuming you have backup-artifacts copied into /bahmni-backup directory
The <restore-artifacts-folder-path>
is the location where you have copied backup data from your old server. Note: Pass the absolute path of the directory as the input
The restore script will now start initialising the database containers one by one based on the db backup files present in the passed restore-artifacts-folder-path
directory. As an example if you have added only openmrsdb_backup.sql
then only openmrsdb container will be started and database will be restored.
Next the restore script will load the bahmni files system backups like patient images, document images etc. into the required volume mounts.
Once the restore script has completed, you can see the list of running containers by running docker ps -a
and the list of volumes created by running docker volume ls
. To validate whether a database has been properly restored, you can exec into the container and connect to the database and validate.
Few useful queries to validate the restore of OpenMRS database:
The below queries can be run inside OpenMRS db container by exec and connecting to MYSQL. (docker compose exec -it openmrsdb bash)
--> List all tables (Approx 246 tables)
SHOW tables;
--> List all procedures in OpenMRS database. You will see entries showing names
SHOW PROCEDURE STATUS WHERE db = 'openmrs';
--> List Routine Information in OpenMRS database
SELECT routine_schema,routine_name,routine_type FROM information_schema.routines WHERE routine_schema = 'openmrs' ORDER BY routine_name;
---> Validate View Creation (You should see a query fetching information from concept related tables)
select VIEW_DEFINITION from information_schema.views where TABLE_NAME='concept_view';
Starting the Bahmni Application Components:
Once the above step has been completed, you will have the database and bahmni files copied and volume mounted into specific locations. Next step is starting the application containers. We recommend doing this in a phased approach.
Starting EMR Components:
As the first step to testing upgrade on Bahmni Docker start with the Bahmni EMR components which includes running OpenMRS with Bahmni Modules, Bahmni Web, Appointments, Implementer Interface. You can start these services by running
docker compose --profile emr up -d
or docker compose --profile emr --env-file <you env file name> up -d
.
Wait for the containers to boot up, run the required migrations. You can also check logs of individual containers by running docker compose logs -f openmrs
or using the ./run-bahmni.sh
utility script
The application should be accessible at https://localhost (or) https://<machine-ip/public-ip>
. You can validate the EMR flows based on your implementation specific configuration.
Once you feel comfortable that you have tested all EMR/Clinical flows, you can proceed with starting the other required services based on your needs.
Starting Reports Components:
You can start the Reports service by running the below command.
docker compose --profile reports up -d
or docker compose --profile reports --env-file <you env file name> up -d
.
The application should be accessible at https://localhost (or) https://<machine-ip/public-ip>
. You can validate reports data between old and new system.
Starting OpenELIS Components:
You can start the OpenELIS Lab Managament system by running the below command.
docker compose --profile openelis up -d
or docker compose --profile openelis --env-file <you env file name> up -d
.
The application should be accessible at https://localhost/openelis (or) https://<machine-ip/public-ip>/openelis
. You can validate patients and lab orders sync properly over atomfeed.
Starting Odoo Components:
You can start Odoo and the odoo-connect service (integration service between EMR and odoo) by running below command.
docker compose --profile odoo-10 up -d
or docker compose --profile odoo-10 --env-file <you env file name> up -d
.
The application should be accessible at https://localhost:8070 (or) https://<machine-ip/public-ip>:8070
. You can validate patients, quotations sync properly over atomfeed.
Starting Radiology (PACS) Components:
Steps to be done before starting Radiology:
Before starting application, update modality table in the pacs_integration database to send orders to dcm4chee running in docker
Updating PACS Query Config
Login to OpenMRS and validate if
Pacs Query
OMOD is running from Administration → Manage Modules.Now navigate to Administration → Settings → PacsQuery and find the
pacsConfig
property.In that property add information about your PACS server from where the order information needs to be fetched. The format would be
<AETitle>@<Host>:<Port>
. Set the value as DCM4CHEE@dcm4chee:11112
Starting the application:
You can start DCM4CHEE and the pacs-integration service by running below command.
docker compose --profile pacs up -d
or docker compose --profile pacs --env-file <you env file name> up -d
.
The application should be accessible at https://localhost/dcm4chee-web3 (or) https://<machine-ip/public-ip>/dcm4chee-web3
. You can validate dcm4chee modality worklist sync properly over atomfeed.
Now you should have all the components of Bahmni Standard running on docker . We recommend thorough testing of all user flows, system sync over atomfeed before moving to production. Also try restore a couple of times in pre-prod and then move to production.
What’s Next:
The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)