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

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, starting with 5.0.0, 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:

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

Background information:

• Add documentation for migrating from 4.x medic/helm-charts to the new production charts in 5.x cht-core
• Hide upgrade button in admin app for k8s deployments, while still allowing staging upgrades
• Remove upgrade service from Helm charts

Token login requires app_url

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:

• Require app_url to be set when enabling token_login

Enabling languages via generated docs

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:

• Deprecate enabling languages through generated docs
• Allow app builders to specify disabled languages in config

Declarative Configuration

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:

• Make declarative config mandatory

CHT 4.0 - 4.4 upgrade to CHT 4.5 first

Deployments running CHT Version 4.0 through 4.4 must upgrade to version 4.5 or later before upgrading to version 5.x. This accounts for changes to ecmaVersion ES linting to version 6.

Background information:

• Increase ecmaversion linting for ddocs

Ensure booleans are used with signoff fields

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:

• Replication fails to filter out reports with needs_signoff set to false

Angular 20 requires Chrome 107 or later

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 

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:

• Upgrade to Angular 20

Non-Breaking 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 .

Additional disk storage required for upgrading

An internal mechanism of CouchDB requires up to 5x disk space when updating views. As a side-effect of all the performance and TCO changes in 5.0.0, some views were either moved or removed, and as a result, two large design documents need reindexing.

In our testing, the total database storage size increased during indexing to 5x, as seen in this graph:

Disk space storage requirement during 5.0.0 upgrade

This issue is not limited to the upgrade to 5.0.0 alone. Any upgrade that requires indexing new views requires additional disk space.

Temporary downtime for replication and online search immediately after upgrade

With the addition of both the disk use reduction feature and replication speed improvements, two indexes need to be built in CouchDB Nouveau after the upgrade. While these indexes are being created, there’s a brief initialization period where the following services will become available shortly:

• Replication for offline users - Replication will start working once the indexing jobs complete. In the meantime, requests will timeout after 1h. Users will see “sync failed” messages.
• Search for online users - Search functionality will return results as soon as indexing finishes.

The indexes build automatically; no manual intervention is required. This is a one-time process that occurs only when upgrading from 4.x to 5.0. Subsequent upgrades from 5.0 to later versions and fresh 5.0 installations are unaffected.

What to expect:

• Small deployments: Indexes typically complete within minutes, and you may not notice any service interruption.
• Large deployments: Index building may take up to 24 hours, depending on data volume.
• All deployments: Services automatically resume normal operation once indexing completes.

Monitoring progress: You can track the indexing progress in real-time by navigating to Fauxton’s active tasks page at /_utils/#/activetasks (for example, https://cht.example.com/_utils/#/activetasks). Once all search_indexer tasks have disappeared from the list, the upgrade is complete and all services are operational.

Background information:

• Reduce disk space with CouchDB Nouveau (TCO)
• Temporary downtime for replication and online search immediately after 5.0 upgrade