Performing a Backup / Restore of Container Data & Files (docker)

This page documents how to perform a Backup of Bahmni Database / Files when using Docker version of Bahmni. You can also refer to this documentation, if you want to restore data from a back up.
Note that a running instance of Bahmni will have multiple services (like OpenMRS, Crater, OpenELIS, Dcm4chee, etc) depending on what are deployed / being used, hence your backup & restore commands should ensure you restore the correct Databases & Files.
Note that since Bahmni performs a two way sync of Patient Data across sub-systems (like between OpenMRS → Crater, or between OpenMRS → DCM4chee, etc), if you restore only ONE of the databases, but don’t restore the other, then the data across databases may go out of sync. It is therefore recommended that you take backups across ALL relevant databases at the same time, and while restoring, restore the “same” ones together – otherwise, one DB might be “ahead” of the “other”, and therefore go out-of-sync.
You may also need to backup/restore Bahmni files, like patient document uploads, lab reports, patient photo, etc which are stored in Bahmni file system and not in the database.

If you are looking to migrate from Bahmni on CentOS to Bahmni on Docker, please refer to this Wiki page.

Backing up Bahmni Lite or Bahmni Standard:

In order to automate backups from services running on docker, bash scripts are written to take backup of different artifacts like databases, patient images, document images, uploaded results etc. A common utility script for backups has been added to bahmni-docker/backup_restore/backup_utils.sh

Pre-requisites:

Before executing the backup script, update the following in the respective backup script under bahmni-lite subdirectory or bahmni-standard sub-directory.

1. BAHMNI_DOCKER_ENV_FILE

This variable holds the configuration on which env file to be used to load different variables like database names credentials etc. Defaults to .env. If you are planning to use a different env file other than .env open the bahmni-docker/bahmni-lite/backup_bahmni_lite.sh file or bahmni-docker/bahmni-standard/backup_bahmni_standard.sh and update the value of BAHMNI_DOCKER_ENV_FILE variable in the script.

2. BACKUP_ROOT_FOLDER

This variable holds the configuration on where to store the backup-artifacts. Defaults to ./backup-artifacts. If you are planning to use a different directory as root folder for backup artifacts open the bahmni-docker/bahmni-lite/backup_bahmni_lite.sh file or bahmni-docker/bahmni-standard/backup_bahmni_standard.sh and update the value of BACKUP_ROOT_FOLDER variable in the script. Note: It is recommended to use absolute path for backup-artifacts rather than relative paths.

Directory structure of backup artifacts generated by script:

The backup script by default creates a sub-folder of the format YYYY-MM-DD_HH-MM-SSwithin the root folder to store the database backup files of individual services. The file artifacts are stored within the root folder itself under sub-directories like patient_images, document_images, uploaded_results, configuration_checksums. If you want to change this behaviour and have the file artifacts also seprate for individual backups, then update the variable name from BACKUP_ROOT_FOLDER to backup_subfolder_path for file system backup commands.

How backup script works:

The backup script has been written to support backup of every component on the same server running both database and application as containers. If you are planning to run database on an external server or a managed service like AWS RDS, you need to tune the script to backup the database from external service/server. You can find the utility functions in bahmni-docker/backup_restore/backup_utils.sh

The backup script first tries to take the backup databases by running either mysqldump or pg_dump within the container by using docker compose exec command against the compose service.
Next the script backup script takes file system backup by running docker compose cp against the compose service.
The script by default tries to backup all artifacts for the given flavour (lite or standard). The script will throw an error message for containers that are not running and proceed to the next backup item. You can also comment specific lines in the respective backup script if you are not using a specific service.
The script also checks the container to be in running state before starting the backup.
If you have a custom service or want to backup additional file system or databse from any new service, you can use the utility function added in bahmni-docker/backup_restore/backup_utils.sh.

Executing the backup script:

Navigate to the directory with which you are running Bahmni.
cd bahmni-standard or cd bahmni-lite.
Update the variables in the script as mentioned above.
Trigger the script by using the command below
./backup_bahmni_lite.sh (or) ./backup_bahmni_standard.sh
Now you can see the backup artifacts getting created in the configured BACKUP_ROOT_FOLDER

Restoring Bahmni Lite or Bahmni Standard:

Pre-requisites:

Clone the default bahmni-docker or your implementation specific docker-compose repository.

Before executing the backup script, update the following in the respective restore script under bahmni-lite subdirectory or bahmni-standard sub-directory.

1. BAHMNI_DOCKER_ENV_FILE

This variable holds the configuration on which env file to be used to load different variables like database names credentials etc. Defaults to .env. If you have used a different env file other than .env open the bahmni-docker/bahmni-lite/restore_bahmni_lite.sh file or bahmni-docker/bahmni-standard/restore_bahmni_standard.sh and update the value of BAHMNI_DOCKER_ENV_FILE variable in the script.

Updating variables in environment configuration file:

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

	Variable Name	Value to be updated
1	`TZ`	The time zone where your previous instance was running. Example: `Asia/Kolkata`
2	`OPENMRS_DB_IMAGE_NAME`	mysql:5.6 (or) mysql:5.7 (Use based on what your previous installation has been running with)
3	`OPENELIS_DB_IMAGE_NAME`	postgres:9.6
4	`ODOO_DB_IMAGE_NAME`	postgres:9.6
5	`OPENELIS_DB_NAME`	clinlims
6	`OPENELIS_DB_USER`	clinlims
7	`OPENELIS_DB_PASSWORD`	clinlims

Directory Strucutre required for restore:

If you have taken backup with the default configuration in the backup script above, the only change would be to copy the recent database backup files which you want to restore from the timestamp subdirectory into the root folder of the backup-artifacts. Also copy the full path where you have your backup artifacts.

How the restore script works:

The restore script first restores databases in the respective database containers for those the backup files are found. The script basically passes the file contents as the input to mysql or psql command directly within the container by firing docker compose exec command.
The file system files such as patient images, document images, uploaded results etc are copied into the respective volume mounts by creating a small bash container which will copy the given files into respective volume mounts.
For adding a new database restore, you can make a copy of the existing restore_db command in the restore script and alter the variables that are passed to the function.
For adding to a new file system restore, follow the steps below
1. Add a volume mount to the docker-compose file and mount to the required service
2. Add the same a volume mount to restore_volumes service in the docker compose file.
3. Now open the bahmni-docker/backup_restore/restore_docker_volumes.sh script and add a new entry for calling the copy_from_restore_to_mount function which will copy contents from restore artifacts to the volume mount.

Executing the restore script:

Navigate to the directory with which you are running Bahmni.
cd bahmni-standard or cd bahmni-lite.
Update the BAHMNI_DOCKER_ENV_FILE variable in the script as mentioned above.
Trigger the script by using the command below
The <restore-artifacts-folder-path> is the location where you have backup data arranged as per the directory structure. Note: Pass the absolute path of the directory as the input
1. For Bahmni-Lite:
  ./restore_bahmni_lite.sh <restore-artifacts-folder-path> Example: ./restore_bahmni_lite.sh /bahmni-backup --> Assuming you have backup-artifacts copied into /bahmni-backup directory
2. For Bahmni-Standard:
  ./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 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.

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.

For Bahmni Standard components you can refer this page: Upgrading Bahmni on CentOS to Bahmni Standard (or Lite) on Docker | Starting the Bahmni Application Components:

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 with EMR flows, you can proceed with starting the other required services based on your needs.

Issue with Patient Document Access

When trying to access patient documents or uploaded-results or uploaded-files, if you get a 403 Forbidden error or 404 Not found error, it is likely due to file permissions issue with restored files. You can fix this by running the below commands on openmrs container

docker compose exec -it openmrs bash
setfacl -R -d -m o::rx -m g::rx /home/bahmni/document_images
setfacl -R -d -m o::rx -m g::rx /home/bahmni/uploaded_results
setfacl -R -d -m o::rx -m g::rx /home/bahmni/uploaded-files
chmod -R 755 /home/bahmni/document_images
chmod -R 755 /home/bahmni/uploaded_results
chmod -R 755 /home/bahmni/uploaded-files

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 Crater Components:

You can start Crater and the crater-atomfeed service (integration service between EMR and crater) by running below command.

docker compose --profile crater up -d or docker compose --profile crater --env-file <you env file name> up -d.

The application should be accessible at https://localhost:444 (or) https://<machine-ip/public-ip>:444. You can validate patients sync properly over atomfeed.