← Back to team overview

dhis2-users team mailing list archive

Upgrading from 2.16 to 2.21 (using dhis2-tools)


I know questions about this comes up now and again.  I just finished
doing exactly this for a regional server today so I list my steps here
for those planning a similar process.

Starting state was a server running ubuntu 12.04, openjdk 7 and dhis2 2.16.

Database backup was made and a copy kept off the server.

1.  Upgrade the OS to 14.04.  This is the longest (and scariest) step
- a big upgrade to do over the internet.  But the recommended
procedure (running 'sudo do-release-upgrade') worked fine.  Took a few
hours.  Ubuntu creates an emergency ssh backdoor on port 1022 while
this is going on, but fortunately I didn't have to use it.  But we did
have ufw firewall running so I took the precaution of opening that
port just in case (sudo ufw allow 1022).

2.  Install oracle java 8 :

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java8-installer
sudo update-java-alternatives -s java-8-oracle

3.  Download all the upgrade scripts and war files
for ver in 17 18 19 20 21;
   wget -O dhis-2.$ver.war
   wget https://raw.githubusercontent.com/dhis2/dhis2-utils/master/resources/sql/upgrade-2$ver.sql

4.  Read carefully all the upgrade notes at:

5.  shutdown nginx with
sudo service nginx stop

6.  start deploying war files and checking logs as we go.  Apply
upgrade scripts as necessary

dhis2-deploy-war -f dhis-2.17.war dhis2; tail -f

dhis2-deploy-war -f dhis-2.18.war dhis2; tail -f

cat upgrade-219.sql |psql dhis2
dhis2-deploy-war -f dhis-2.19.war dhis2; tail -f

cat upgrade-220.sql |psql dhis2
dhis2-deploy-war -f dhis-2.12.war dhis2; tail -f

7.  clear nginx cache and restart
sudo -s
rm /var/cache/nginx/*
sudo service nginx start

That's about it.  So far everything seems ok.  We just hope there are
not problems from messy metadata.  Probably it is a better I idea to
do integrity checks on the metadata right at the very start (I

Note I am holding back on 2.21 upgrade because of the issue with md5
passwords mentioned in the upgrade notes.   I'll give the users a day
or two to make sure they have tested their logins.  Will take 5
minutes to do when the time comes.

Note that the OS upgrade is necessary to get the right tomcat version
through the package system.  We could have avoided by doing a custom
tomcat install, but I prefer to stick with the packages.

Hope the above helps anyone else faced with this challenge.


Follow ups