Host
CHT Core
Migration Guides
Preparing for 5.0

Preparing to Upgrade to CHT 5.0

Steps to ensure your CHT App will run smoothly on CHT 5.0 and later

Introduction

CHT releases use Semantic Versioning (also known as “SemVer”), which means that the CHT upgrade from the major 4.x version to the 5.x version denotes there are breaking changes. The key to a successful upgrade will be to understand and plan for these breaking changes.

As with all upgrades, major or minor, you should always:

  • Have backups that have been tested to work
  • Ensure your CHT Conf version is up to date
  • Review the change log to understand how end users might be affected
  • Check troubleshooting upgrades guide if the upgrade doesn’t succeed

Read though this entire document before upgrading and pay special attention to the “Breaking Changes” section to know which of of the changes are applicable.

Breaking Changes

Upgrade service removed from Kubernetes

Applies to: Kubernetes hosted CHT instances

In CHT 4.x there are two ways to upgrade a Kubernetes hosted CHT instance:

  1. Click “Stage” and then “Upgrade” in the CHT administration interface.
  2. Push a new helm chart to Kubernetes that specified different versions.

A recurring problem seen on production deployments was that, over time, CHT administrators would use the CHT administration interface to upgrade. Then, during a migration or a restore from backup, Kubernetes administrators would inadvertently downgrade a CHT instance by using an out of date Helm chart.

To avoid this situation, the “Upgrade” button has been removed from Kubernetes based deployments, so only the “Stage” button will show. Here is a mockup of what it look like:

k8s.no.upgrade.button.png

Deployments which used the now deprecated CHT 4.x Helm Charts, will need migrate to the 5.x charts, now moved to the CHT Core repository.

Background information:

Token login requires app_url

Applies to: Instances that use token login

For instances that use token login, be sure to declare app_url in your settings file. This is backwards compatible and safe to do while still on CHT 4.x.

Background information:

Enabling languages via generated docs

Applies to: Instances that enable languages via web interface

As of CHT 4.2.0, deployment administrators can enable or disable supported languages via the settings file.

Before upgrading, ensure your app settings has the correct languages enabled. This is backwards compatible and safe to do while still on CHT 4.x. If you’re unsure if this applies to you, double check your app settings.

If languages is not set, the login screen will show all languages. Fix it by declaring the languages per above.

Background information:

Declarative Configuration

Applies to: All Instances

Deployments that have not compiled their app settings config in a very long time with a new version of CHT Conf, when logging in as an offline user may see, Error: Rules Engine: Rules are not declarative. Updates are required.

Additionally, the web developer console will show:

Error selecting contact Error: Rules Engine: Rules are not declarative. Updates are required.
ERROR Error: Uncaught (in promise): TypeError: Cannot read properties of null (reading 'doc')
TypeError: Cannot read properties of null (reading 'doc')

The fix is to:

  1. Update CHT Conf to be current
  2. Recompile the app settings and upload them to the CHT. Be sure to replace the value of --url to the current password, URL and port: cht --url=https://medic:password@example.com:12345 compile-app-settings upload-app-settings

Background information:

Increase ecmaVersion ES linting to version 6

Applies to: CHT versions between 4.0 and 4.4

Deployments running CHT Version 4.0 and 4.4 must upgrade to version 4.5 or later before upgrading to version 5.x.

Background information:

Ensure booleans are used with signoff fields

Applies to: Instances where needs_signoff triggers replication of reports

In some scenarios where needs_signoff is set to string "false" instead of boolean false, replication will happen when it shouldn’t. This is because the string of "false" is a truthy value.

CHT 5.0 now correctly enforces this to be a boolean. Deployments to make sure that workflows that use needs_signoff field have a boolean instead of a string.

Background information:

Angular 20 requires Chrome 107 or later

Applies to: all instances

CHT 5.0 is preparing for an upgrade to Angular 20. As this version of Angular will require Chrome 107 or later, we’re making this a requirement in 5.0 as a breaking change to pave the path for the upgrade later. When researching the impact of this upgrade we surveyed over 100,000 end users devices and found that less than 0.5% of users are affected. These users are running Chrome 106 released 3 years ago at this writing. A best practice is to have users always run the latest version if possible.

To check if any of your users are impacted, check the user-devices API. This is an authenticated API endpoint and will return JSON for all users for all time. As this may include multiple entries per user, it’s important to filter out duplicate users and those running Chrome 107 or later.

Before starting, be sure curl, jq and sort are installed. In Ubuntu server, this looks like: sudo apt update&&sudo apt install jq coreutils curl. After confirming these tools are installed, save the output of the API to a JSON file being sure to replace user, password and URL with their correct values for your production instance:

curl https://user:password:URL/api/v2/export/user-devices > devices.json
For large instances with more than 2,000 users, run the API call after hours. It can have an adverse impact on CHT server performance.

Now that you have the devices.json JSON file, flatten it into a CSV file with just one row per user. Note that we’re only finding users of the APK (select(.apk|length> 0)) and the Chrome browser (select(.browser.name == "Chrome"). This excludes desktop and Firefox users which will show up in the JSON as well. Finally, we’re also only showing users active since 2025-04-01, 6 months ago as of this writing (select(.date > "2025-04-01")). Be sure to update this date to be a relative 6 months ago from when you run the command:

jq -r '.[] |  select(.apk|length> 0) 
  | select(.browser.name == "Chrome")
  | select(.date > "2025-04-01")
  | "\(.deviceId) \(.user) \(.date) \(.browser.version)"' \
  devices.json | sort -u -k1,2r \
  | sort -u -k1,1 | cut -f2,3,4 -d' '| sort -rh -k3 \
  | sed 's/ /,/g' > devices.csv

The resulting file devices.csv will have all of your users sorted by the version of Chrome they use. Scroll to the bottom and find any users running a version lower than 107 and ensure they update to a newer version. The easiest way to upgrade is to open the Play Store and update any out of date software, being sure to update WebView.

For instances with users who share devices, or have multiple devices they log in on, they may have multiple entries. This is because the CHT creates one entry per device per user. Be sure to upgrade all affected devices!

Background information:

Non-Breaking Changes

These changes apply to all deployments. No specific action is required, but administrators should be aware of the changes.

CouchDB Nouveau

A major feature of CHT 5.0 is replacing the freetext search in 4.x with CouchDB Nouveau. The addition of Nouveau decreases the amount of disk space used by the CHT. Disk space is a major contributor to hosting costs, hence Nouveau is a feature meant to reduce Hosting Total Cost of Ownership (TCO).

Nouveau has the following impact on all CHT deployments upgrading to 5.0:

  • Offline users’ devices will have their search indexes rebuilt after the upgrade. During the rebuild, search functionality will be initially unavailable. However, once indexing is complete, the search behavior will remain unchanged for all users: the search experience is the same in both CHT 4.x and CHT 5.x.
  • The Nouveau index data on the server will be stored in ${COUCHDB_DATA}/nouveau for single-node CouchDBs and in ${DB1_DATA}/nouveau for clustered CouchDBs.
  • The following medic-client views no longer exist. Be sure to update any custom scripts which use them: contacts_by_freetext, contacts_by_type_freetext and reports_by_freetext .

Background information:

Last updated on

Did this documentation help you ?

To Docker Single-NodePreparing for 4.0