The Challenge
When the National Tuberculosis Control Centre (NTCC) asked us to upgrade their DHIS2 instance from version 2.33.3 to 2.36, the stakes were high. The system was not a pilot — it was the live national platform carrying years of TB patient tracker data, DRTB (Drug-Resistant TB) treatment records, GeneXpert test results, and monthly aggregate reports from health facilities across all 77 districts of Nepal.
A failed upgrade would not just be a technical problem. It would disrupt real-time TB monitoring for an entire country.
This post documents how we approached it, what we learned, and what any DHIS2 implementer should know before attempting a major version upgrade on a production system with live tracker data.
Why Upgrade at All?
DHIS2 2.33 was reaching its support limits, and several features the TB programme needed simply did not exist in that version:
- Improved Tracker APIs for the Presumptive TB Register and Active Case Finding modules we were building in parallel
- Better aggregate-to-tracker linking needed for GeneXpert-to-HMIS data push via API
- SMS notification infrastructure — 2.36 offered far more stable outbound messaging support
- Performance improvements — 2.33 had known query performance issues under high concurrent load during monthly reporting windows
The upgrade was not optional. It was a prerequisite for the next phase of the system.
Why Not Upgrade Directly to v2.36?
This is the question most people ask first, and the answer is important: you cannot safely jump multiple DHIS2 major versions in a single step.
DHIS2's database migration scripts are designed to run sequentially. Each version includes migrations that assume the previous version's schema is in place. Skipping versions risks:
- Orphaned foreign keys and broken references in the database
- Silent data corruption that only surfaces weeks later in reports
- Programme rules and indicators that silently stop evaluating correctly
Our upgrade path was:
v2.33.3 → v2.34 → v2.35 → v2.36
Three sequential upgrades, each tested fully before proceeding to the next.
Pre-Upgrade Preparation
Full Database Backup
Before touching anything, we took a complete PostgreSQL dump of the production database. Then we took another one. The backup was stored in two separate locations — one on the same Proxmox hypervisor (different volume), one transferred offsite.
This sounds obvious, but it is worth stating: the backup is not a backup until you have confirmed it can actually restore. We ran a full restore to a staging environment and verified the DHIS2 instance came up correctly before proceeding.
Staging Environment
We spun up a staging server running the identical Proxmox configuration as production — same OS version, same PostgreSQL version, same JVM settings. The staging instance was loaded with the production database backup.
Every upgrade step was run on staging first. We documented the exact sequence of commands, configuration changes, and any manual SQL fixes required. The production upgrade was essentially a replay of a documented, tested procedure.
Dependency Audit
DHIS2 2.36 requires a newer Java version than 2.33. We audited:
- Java version compatibility (moved from Java 8 to Java 11)
- Tomcat version requirements
- PostgreSQL compatibility (we were on 10, upgraded to 12 in parallel)
- Any custom DHIS2 apps that might break with the API changes in 2.36
The custom apps — particularly the GeneXpert dashboard and the DRTB tracking modules — needed compatibility review against the updated API contracts.
The Upgrade Process
Step 1: v2.33.3 → v2.34
The first hop was the most nerve-wracking. After stopping the Tomcat service, replacing the WAR file, and starting the server, DHIS2 runs its Flyway migration scripts automatically on startup. The logs show each migration as it runs.
On staging, the first startup took 23 minutes as migrations ran. On production, we expected longer given the data volume.
Issue encountered on staging: Two custom programme indicators that used expressions not valid in the new API format. DHIS2 logged these as warnings, not errors — meaning the system came up successfully but those indicators silently returned null. We fixed the indicator expressions before running on production.
Step 2: v2.34 → v2.35
This hop was straightforward. The only notable change was a schema modification to how DHIS2 stores sharing settings — the migration handled it automatically, but we verified that user group sharing on all TB datasets was preserved correctly after the upgrade.
We also ran the DHIS2 integrity checks (api/maintenance/dataPruning and api/resourceTables/generate) at this stage to clean up any orphaned data before the final hop.
Step 3: v2.35 → v2.36
The final hop introduced the most significant API changes, particularly around tracker data. DHIS2 2.36 partially deprecated the old /api/trackedEntityInstances endpoint in favour of the new /api/tracker endpoint family.
Our custom middleware — which pushed GeneXpert machine data from the lab system into DHIS2 via the tracker API — was written against the old endpoint. We updated the middleware to use the new API before upgrading production, and ran both endpoints in parallel during a two-week testing window to confirm data parity.
What We Delivered Alongside the Upgrade
The upgrade itself was the foundation. Alongside it, we delivered several new capabilities the TB programme had been waiting for:
TB Laboratory System improvements:
- GeneXpert report generation aggregated by sex and site, aligned with HMIS reporting format
- API integration pushing GeneXpert and microscopy results directly to the national HMIS — eliminating the manual double-entry that had been the source of data discrepancies
- Biometric system integration for patient identification at laboratory entry points
- Automatic sample detail updates when GeneXpert results were received from machines
DRTB Tracking enhancements:
- Support for both standard and modified drug regimens — previously the system only tracked standard regimens, meaning modified treatment cases were recorded inconsistently
- Treatment regimen-specific reporting by site, district, and province
- Improved RIF Enrolment Analysis module
New modules:
- Presumptive TB Register — a full frontend and backend module for recording patients assessed for TB before diagnosis confirmation
- Active Case Finding (ACF) tracker — for community-level TB screening campaigns
SMS notification infrastructure: Patients and facility staff now receive automated SMS notifications at key points in the TB care pathway — test result availability, treatment milestones, and missed appointment alerts.
The Production Cutover
We scheduled the production upgrade for a Saturday morning — the lowest activity period for the system. The NTCC programme team sent advance notice to district health offices that the system would be unavailable for a maintenance window.
The actual downtime was 4 hours and 17 minutes. We had budgeted 6 hours. The time breakdown:
| Step | Time |
|---|---|
| Final database backup | 22 min |
| v2.33 → v2.34 migration | 41 min |
| Verification and integrity checks | 28 min |
| v2.34 → v2.35 migration | 34 min |
| Verification | 19 min |
| v2.35 → v2.36 migration | 51 min |
| Custom app compatibility testing | 38 min |
| Final verification and sign-off | 24 min |
The system came up on 2.36 with all tracker data, all programmes, all custom apps, and all user accounts intact. No records lost. No reports broken.
Lessons for Other DHIS2 Implementers
Never skip versions. The sequential hop approach takes longer but eliminates an entire class of data integrity risks.
Test custom app API compatibility before the upgrade, not after. Any code touching /api/trackedEntityInstances, /api/events, or indicator expressions needs review before each major version hop.
Run integrity checks between each version hop. DHIS2's built-in integrity tools catch issues that would otherwise surface as mysterious report discrepancies months later.
The staging environment must be production-equivalent. Staging upgrades that go perfectly on an underprovisioned server may fail or behave differently on the production box if JVM heap and PostgreSQL connection pool settings differ.
Build in rollback time. We kept the v2.33 database backup mounted and accessible throughout the upgrade window. Had anything gone wrong, we could have restored to the original state within 30 minutes.
Where the System Stands Now
The NTCC DHIS2 instance running on 2.36 now serves as the central hub for Nepal's national TB programme — tracking patients from presumptive assessment through laboratory testing, treatment enrolment, and outcome recording. The new API integrations mean data that was previously entered twice (once in the lab system, once in DHIS2) is now entered once and flows automatically.
If your organisation is running an older DHIS2 version and considering an upgrade, we are happy to discuss the path. The fundamentals are the same regardless of which country or programme you are working with.
Get in touch with Hello World to talk through your upgrade requirements.
Hello World IT Solutions specialises in DHIS2 implementation, upgrade, and custom module development for national health programmes across Nepal and South Asia.