diff --git a/content/en/community/contributing/code/core/collect-forms-update.md b/content/en/community/contributing/code/core/collect-forms-update.md index 5115826e80..428b20ca89 100644 --- a/content/en/community/contributing/code/core/collect-forms-update.md +++ b/content/en/community/contributing/code/core/collect-forms-update.md @@ -7,7 +7,7 @@ description: > aliases: - /apps/guides/updates/collect-forms-update - - /building/guides/updates/collect-forms-update + - /building/guides/updates/collect-forms-update/ --- To do over the air Medic Collect form updates via HTTP rather than sending APKs which have a long manual install process, follow the steps below: diff --git a/content/en/hosting/cht/migration/helm-charts-4x-to-5x-migration.md b/content/en/hosting/cht/migration/helm-charts-4x-to-5x-migration.md index ae8dee643e..aa00f672cb 100644 --- a/content/en/hosting/cht/migration/helm-charts-4x-to-5x-migration.md +++ b/content/en/hosting/cht/migration/helm-charts-4x-to-5x-migration.md @@ -1,4 +1,8 @@ -# CHT 4.x to 5.x Helm Charts Migration Guide +--- +title: "CHT 4.x to 5.x Helm Charts Migration Guide" +linkTitle: "Helm Charts 4.x to 5.x" +weight: 70 +--- ## Overview diff --git a/content/en/hosting/cht/migration/preparing-for-4.md b/content/en/hosting/cht/migration/preparing-for-4.md index 60e83c77c1..8fe0a84cb3 100644 --- a/content/en/hosting/cht/migration/preparing-for-4.md +++ b/content/en/hosting/cht/migration/preparing-for-4.md @@ -1,21 +1,17 @@ --- title: "Preparing to upgrade to CHT 4.0" -linkTitle: "Preparing to upgrade to CHT 4.0" -weight: +linkTitle: "Preparing for 4.0" +weight: 60 aliases: - /apps/guides/hosting/3.x/preparing-for-4.0 - /apps/guides/updates/preparing-for-4.md - /apps/guides/updates/preparing-for-4/ - /building/guides/updates/preparing-for-4/ -date: 2022-09-01 description: > Steps to ensure your CHT App will run smoothly on CHT 4.0 and later --- -> [!NOTE] -> This guide applies to both self-hosted and Medic hosted deployments. - ## Introduction Medic uses [Semantic Versioning](https://en.wikipedia.org/wiki/Semver#Semantic_versioning) (aka "SemVer") which means that the CHT upgrade from the major 3.x version to the 4.x version denotes there are breaking changes. The key to a successful upgrade will be to understand and plan for these breaking changes. Aside from the Docker hosting infrastructure (out of scope for this prep document), the two breaking changes are around CHT Android and Enketo. diff --git a/content/en/hosting/cht/migration/preparing-for-5.md b/content/en/hosting/cht/migration/preparing-for-5.md new file mode 100644 index 0000000000..dcaa5e91b5 --- /dev/null +++ b/content/en/hosting/cht/migration/preparing-for-5.md @@ -0,0 +1,166 @@ +--- +title: "Preparing to Upgrade to CHT 5.0" +linkTitle: "Preparing for 5.0" +weight: 50 +description: > + Steps to ensure your CHT App will run smoothly on CHT 5.0 and later +--- + +## Introduction + +CHT releases use [Semantic Versioning](https://en.wikipedia.org/wiki/Semver#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]({{< relref "/hosting/cht/docker/backups/" >}}) that have been tested to work +* Ensure your [CHT Conf]({{< relref "/community/contributing/code/cht-conf/" >}}) version is up to date +* Review the change log to understand how end users might be affected +* Check [troubleshooting upgrades](/hosting/cht/upgrade-troubleshooting/) 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 + +{{< callout type="info" >}} Applies to: [Kubernetes]({{< relref "/hosting/cht/kubernetes/" >}}) hosted CHT instances {{< /callout >}} + +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](preparing-for-5/k8s.no.upgrade.button.png) + +Deployments which used the now deprecated [CHT 4.x Helm Charts](https://github.com/medic/helm-charts/), will need [migrate](/hosting/cht/migration/helm-charts-4x-to-5x-migration/) to the [5.x charts](/hosting/cht/migration/helm-charts-4x-to-5x-migration/), 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](https://github.com/medic/cht-docs/issues/1943) +* [Hide upgrade button in admin app for k8s deployments, while still allowing staging upgrades](https://github.com/medic/cht-core/issues/9954) +* [Remove upgrade service from Helm charts](https://github.com/medic/cht-core/issues/10186) + +### Token login requires `app_url` + +{{< callout type="info" >}} Applies to: Instances that use [token login]({{< relref "/building/login/#magic-links-for-logging-in-token-login" >}}) {{< /callout >}} + +For instances that use token login, be sure to declare `app_url` in your [settings file]({{< relref "/building/reference/app-settings/token_login/#app_settingsjson-token_login" >}}). 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`](https://github.com/medic/cht-core/issues/9983) + +### Enabling languages via generated docs + +{{< callout type="info" >}} Applies to: Instances that enable languages via web interface {{< /callout >}} + +As of [CHT 4.2.0]({{< relref "/releases/4_2_0/#technical-improvements" >}}), deployment administrators can enable or disable supported languages [via the settings file]({{< relref "/building/reference/app-settings/#app_settingsjson" >}}). + +Before upgrading, ensure [your app settings]({{< relref "/building/reference/app-settings/#app_settingsjson" >}}) 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](https://github.com/medic/cht-core/issues/8157) +* [Allow app builders to specify disabled languages in config](https://github.com/medic/cht-core/issues/6281) + + +### Declarative Configuration + +{{< callout type="info" >}}Applies to: All Instances{{< /callout >}} + +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: + +```shell +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](/community/contributing/code/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](https://github.com/medic/cht-core/issues/5906) + +### Increase ecmaVersion ES linting to version 6 + +{{< callout type="info" >}} Applies to: CHT versions between 4.0 and 4.4 {{< /callout >}} + +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: +* [Increase ecmaversion linting for ddocs](https://github.com/medic/cht-core/issues/9202) + +### Ensure booleans are used with signoff fields + +{{< callout type="info" >}} Applies to: Instances where `needs_signoff` triggers replication of reports {{< /callout >}} + +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](https://github.com/medic/cht-core/issues/10183) + +### Angular 20 requires Chrome 107 or later + +{{< callout type="info" >}} Applies to: all instances {{< /callout >}} + +CHT 5.0 is preparing for an upgrade to [Angular 20](https://blog.angular.dev/announcing-angular-v20-b5c9c06cf301). 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](https://github.com/medic/cht-core/issues/10029#issuecomment-3358338361) 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](/building/reference/api/#get-apiv2exportuser-devices). 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: + +```shell +curl https://user:password:URL/api/v2/export/user-devices > devices.json +``` + +{{< callout type="warning" >}} +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. +{{< /callout >}} + +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: + +```shell +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](https://play.google.com/store/apps/details?id=com.google.android.webview&hl=en). + +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](https://github.com/medic/cht-core/issues/10029) + + +## Non-Breaking Changes + +{{< callout >}} +These changes apply to all deployments. No specific action is required, but administrators should be aware of the changes. +{{< /callout >}} + +### 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](https://github.com/medic/cht-core/issues/9898#issuecomment-2864545914) 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)](https://github.com/medic/cht-roadmap/issues/171). + +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: +* [Reduce disk space with CouchDB Nouveau (TCO)](https://github.com/medic/cht-core/issues/9542) diff --git a/content/en/hosting/cht/migration/preparing-for-5/k8s.no.upgrade.button.png b/content/en/hosting/cht/migration/preparing-for-5/k8s.no.upgrade.button.png new file mode 100644 index 0000000000..5a081b7824 Binary files /dev/null and b/content/en/hosting/cht/migration/preparing-for-5/k8s.no.upgrade.button.png differ diff --git a/content/en/hosting/cht/upgrade-troubleshooting.md b/content/en/hosting/cht/upgrade-troubleshooting.md index c9a777183b..64febf8aca 100644 --- a/content/en/hosting/cht/upgrade-troubleshooting.md +++ b/content/en/hosting/cht/upgrade-troubleshooting.md @@ -10,10 +10,6 @@ aliases: - /hosting/4.x/upgrade-troubleshooting/ --- -{{< callout >}} - 4.0.0 was released in November of 2022 so 4.x is mature and users have learned a number of important lessons on how to fix failed upgrades. Below are some specific tips as well as general practices on upgrading. -{{< /callout >}} - There's a concept of upgrades "getting stuck" which mainly means that after many many hours an upgrade is not making any progress. Most likely, this will manifest as the progress bars in the upgrade admin web UI not increasing and "sticking" at a certain percentage. An alternate possibility is that the progress bars disappear altogether. > [!WARNING] @@ -34,6 +30,31 @@ A safe fix for any upgrade getting stuck is to restart all services. Any views If you're able to, after a restart go back into the admin web GUI and try to upgrade again. Consider trying this at least twice. +## CHT 4.18.0 - 4.21.1: Error triggering update + +**[Issue #10296](https://github.com/medic/cht-core/issues/10296)**: Requests will fail due to fetch implementation if headers are not sent within 5 minutes + +API error: + +```shell +TypeError: fetch failed + at node:internal/deps/undici/undici:15445:13 + at async /home/diana/.config/JetBrains/WebStorm2025.2/scratches/fetchtimeout.js:2:13 { + [cause]: HeadersTimeoutError: Headers Timeout Error + at FastTimer.onParserTimeout [as _onTimeout] (node:internal/deps/undici/undici:6821:32) + at Timeout.onTick [as _onTimeout] (node:internal/deps/undici/undici:528:17) + at listOnTimeout (node:internal/timers:608:17) + at process.processTimers (node:internal/timers:543:7) { + code: 'UND_ERR_HEADERS_TIMEOUT' +} +``` + +**Fix:** +1. Wait until there are no more [active tasks](https://michellephung.github.io/Fauxton-Visual-Guide/#page-active-tasks). +2. When there are no more active tasks, start the same upgrade again from the admin UI. It should succeed without any errors this time. + +{{< figure src="upgrade.again.png" link="upgrade.again.png" caption="Admin web GUI showing 'Error triggering update' message at the top, and an arrow pointing to 'Install' button as the next step" >}} + ## CHT 4.0.x - 4.3.x: CouchDB Crashes **[Issue #9286](https://github.com/medic/cht-core/issues/9286)**: Starting an upgrade that involves view indexing can cause CouchDB to crash on large databases (>30m docs). The upgrade will fail and you will see the logs below when you have this issue. diff --git a/content/en/hosting/cht/upgrade-troubleshooting/upgrade.again.png b/content/en/hosting/cht/upgrade-troubleshooting/upgrade.again.png new file mode 100644 index 0000000000..17c43aa349 Binary files /dev/null and b/content/en/hosting/cht/upgrade-troubleshooting/upgrade.again.png differ