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

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:

1. 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.

2. Next the script backup script takes file system backup by running docker compose cp against the compose service.

3. 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.

4. The script also checks the container to be in running state before starting the backup.

5. 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:

1. Navigate to the directory with which you are running Bahmni.
   cd bahmni-standard or cd bahmni-lite.

2. Update the variables in the script as mentioned above.

3. Trigger the script by using the command below
   ./backup_bahmni_lite.sh (or) ./backup_bahmni_standard.sh

4. 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

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:

1. 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.

2. 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.

3. 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.

4. 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:

1. Navigate to the directory with which you are running Bahmni.
   cd bahmni-standard or cd bahmni-lite.

2. Update the BAHMNI_DOCKER_ENV_FILE variable in the script as mentioned above.

3. 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

4. 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.

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.