Upgrade Quick Guide_1.6.9

Upgrade Quick Guide_1.6.9

DBSYNC UPGRADE QUICK GUIDE

Introduction

This document provides a quick guide for upgrading the remote DBSYNC environment to version 1.6.9, which is compatible with the OpenMRS 2.3.x platform.

For upgrades to the latest DBSYNC 1.9.0 version (compatible only with OpenMRS 2.6.x), please refer to the OpenMRS Platform 2.6.11 Upgrade SOP, released in March 2025.

If your system is already running OpenMRS 2.6.11, please follow the instructions in the “Upgrade Quick Guide 1.9.0.”

There are three upgrade processes depending on your current DBSYNC environment:

1.     
Online Docker installation
– Recommended for sites with a stable internet connection.

2.     
Native installation
– For environments not using Docker.

3.     
Offline Docker installation
– For Docker environments with limited or unreliable internet access.

Choose the appropriate process based on your setup and follow the respective instructions carefully.

Before You Start

For all the environments you must perform below steps, and then follow your specific environment steps:

  1. Log in as “eip” user.

su - eip

  1. Create a temporary variable for eip home

export HOME_DIR=/home

export EIP_HOME=$HOME_DIR/eip

  1. Change current directory to eip home

cd $EIP_HOME

  1. If you are running dbsync on Docker based installation, down the DBSYNC container:

docker-compose down

  1. If you are running DBSYNC on non-Docker based [or native] installation, stop the DBSYNC service:

sudo systemctl stop eip

or

sudo service eip stop

  1. Create a backup folder for old DBSYNC stuff:

sudo mkdir $HOME_DIR/eip_bkps

  1. Change the owner of the backup folder

sudo chown -R eip $HOME_DIR/eip_bkps

  1. And the owner of all stuff on eip home

sudo chown -R eip $EIP_HOME

  1. Move all older DBSYNC stuff to backup folder. Run the two commands bellow on-by-one:

shopt -s dotglob

 

mv $EIP_HOME/* $HOME_DIR/eip_bkps/

 

 

  1. Create the eip debezium dir

 

mkdir -p $EIP_HOME/shared/.debezium

  1. Restore the eip.env file from old stuff

cp $HOME_DIR/eip_bkps/eip.env $EIP_HOME/

 

  1. Restore the debezium files from old stuff:

 

cp -R $HOME_DIR/eip_bkps/shared/.debezium/* $EIP_HOME/shared/.debezium/

 

  1. Edit the $EIP_HOME/eip.env file removing the lines containing the following properties if they are present:

 

dbsync_notification_email_smtp_auth_user=

dbsync_notification_email_smtp_user_pass=

dbsync_notification_email_smtp_host_name=

dbsync_notification_email_smtp_host_port=

system_user=

artemis_ssl_enabled=true

system_password=

  1. Add the below properties on the eiv.env file. These are credentials for the DBSYNC console. You must use the username and password which appear on the file $HOME_DIR/eip_bkps/release_stuff/dbsync-users.properties

eip_user=

eip_pass=

 

  1. From this point follow your environment specific guide.

Upgrade process for Docker based environment (Online based Installation
[1]
)

If your environment is an online based installation running any older version of DBSYNC follow the below steps.

Make sure you follow the instructions on the topic “Before You Start” and you are under the $EIP_HOME directory.

  1. Recreate the Docker repository

 

git init && git checkout -b main

 

  1. Add remote Docker repository

 

 

  1. Pull the remote project into the local repository

 

git pull --depth=1 origin main

  1. Create the container using the command bellow:

docker-compose up -d

  1. Follow the container logs

docker logs --follow dbysync-remote

 

  1. Wait until the DBSYNC is started and then if no error is reported, congratulations, You Are Done!

 

Upgrade process for Docker based environment (Off-line based Installation
[2]
)

If you are upgrading any offline Docker based installation, please follow the steps below.

Make sure you follow the instructions on the topic “Before You Start” and you are under the $EIP_HOME directory.

  1. Remove the DBSYNC local docker image

docker image rm openmrs-eip-sender

  1. Copy the DBSYNC package stuff (eip_home.tar.gz) to eip home dir ($EIP_HOME).
  2. Uncompress the package file using the command bellow:

tar -xf eip_home.tar.gz

  1. Re-import the DBSYNC image to docker local storage:

docker import docker_images/dbsync-remote.tar dbsync-remote:latest

  1. Create the container using the command bellow:

docker-compose up -d

  1. Follow the container logs

docker logs --follow dbsync-remote

 

  1. Wait until the DBSYNC is started and then if no error is reported, congratulations, You Are Done!

 

Upgrade process for Non Docker based environment

If your environment is non Docker based:

Make sure you followed the instructions on the topic “Before You Start” and you are under $EIP_HOME directory.

  1. Remove the old installation directory stuff

sudo rm
-
fr /home/openmrs-eip-docker/*

 

  1. Now enter the installation directory

 

cd /home/openmrs-eip-docker

 

  1. Now, recreate the repository

git init && git checkout -b main

 

  1. Add remote Docker repository

 

 

  1. Pull the remote project into the local repository

 

git pull --depth=1 origin main

 

  1. Create the eip debezium dir

 

mkdir
-
p $EIP_HOME/shared/.debezium

  1. Perform the dependency installation using the command below:

sudo /home/openmrs-eip-docker/release_stuff/scripts/apt_install.sh

 

  1. Perform the installation using the command below:

/home/openmrs-eip-docker/install.sh

  1. Stop the eip application

$EIP_HOME/scripts/eip_stop.sh

  1. Reinstall the eip service

sudo cp $EIP_HOME/scripts/eip.service /etc/systemd/system/

sudo systemctl daemon-reload

sudo systemctl enable eip

  1. Restart the eip service

sudo systemctl start eip

or

sudo service eip restart


An online based installation is the one done pulling the DBSYNC stuff from the GitHub. In other hand there is offline installation which is based on Docker images.

An off-line based installation is the one done downloading the DBSYNC Docker images from the installation package and manually install them on the host. The offline installation usually is used on the remote sites where there is lack of internet connection.


    • Related Articles

    • Dbsync 1.8 Upgrade Quick Guide

      Note Starting from DBsync version 1.7, DBsync can only run on OpenMRS 2.6+ platforms. Consequently, we are not providing the upgrade guide at this time, as the current implementation of OpenMRS is based on the OpenMRS 2.3.x platform. The upgrade ...

    • Upgrade Quick Guide_1.9.0

      DBSYNC UPDATE QUICK GUIDE Introduction This document is a quick guide to upgrade the remote DBSYNC environment from version 1.8.x to version 1.9.0. If you are still running the old OpenMRS 2.3.x version and want to upgrade to the last version of ...

    • Upgrade Quick Guide_1.6.8_and_1.8.1

      Upgrade Quick Guide_1.6.8_and_1.8.1

    • RPS_Installation_Guide

      RPS_Installation_Guide

    • Dbsync 1.8 Packages

      NOTES Starting from DBsync version 1.7, DBsync can only run on OpenMRS 2.6+ platforms. Consequently, we are not providing the packages at this time, as the current implementation of OpenMRS is based on the OpenMRS 2.3.x platform. The upgrade process ...