When upgrading to any version of Smile CDR, you should always read the upgrade notes, which cover any large breaking changes that may require administrator intervention.
In addition to that, if you are upgrading to or past the versions below, you should read the specific sections pertaining to the version of Smile CDR you are upgrading to. These sections indicate operational changes which may not be effectively captured in upgrade notes.
When upgrading CDR from versions older than 2019.08.R01 to a version on or after 2019.08.R01, if subscriptions are enabled, then you will need to add a new Subscription Matching Module of the same FHIR version as your FHIR Storage module and link the Subscription Matching module to that FHIR Storage module as a dependency.
In Smile CDR 2020.02.R01, the clustering mechanism for Smile CDR was completely redesigned. This was done in order to simplify clustering and in particular to make it easier to support Docker-based clustering mechanisms such as Kubernetes.
On this page, we will refer to this new clustering design as 2020.02 clustering, and the previous design as 2019.11 clustering.
The primary change to be aware of in the 2020.02 clustering is that the concept of Master Nodes and Clone Nodes has been completely removed. It is still possible to design clusters that perform functionally identically to 2019.11 clustering, but you will no longer need to explicitly designate one of your nodes as a Master and the rest as Clone nodes.
Instead you will create one or more nodes, each having a set of modules. If you wish to scale any of these nodes up, you will simply start more Smile CDR processes with the same Node ID and Cluster Manager module configuration.
The following table shows key concepts from the old and new clustering mechanisms.
| 2019.11 Cluster Concept | 2020.02 Equivalent |
|---|---|
| Master Node | Node + 1st Node Process |
| Clone Node | Node + subsequent Node Processes |
In this version, automatic upgrade at boot was introduced via the update_mode property. This upgrade method is no longer recommended.
online mode upgrades were added as a concept in this version. Versions before this are not able to take advantage of online upgrades.
The docker container no longer runs as root as of this release. This change is to improve local security. The following actions are required to upgrade to a non-root based docker container structure:
smilesudo chown -R $USER /path/to/volume-mount
Usage of the CDR_UPGRADE_MODE system property is available from this version onwards.
Q: How do you recommend I upgrade my production Smile CDR Cluster? A: Follow the upgrade guide for an example of upgrading a production Smile CDR cluster.
Q: How do I know how long a migration will take? A: We maintain a Database Upgrade Impact Matrix showing relative impacts of migrations on each version.
Q: How do I handle upgrades if I want to have no downtime on the cluster? A: Perform an Online Mode upgrade, gradually upgrading nodes while maintaining service.
Q: What should I do if my upgrade fails? A: In most cases, roll forward rather than back. Database migrations are one-way, so completing the upgrade is usually faster and lower-risk than reverting. If the migration itself failed partway through, correct the underlying cause and run it again; tasks that already succeeded are skipped. If you must revert, use your pre-upgrade backups to restore all affected databases to their previous state. Contact Smile Digital Health support for assistance.
Q: Can I roll back to the previous version of Smile CDR by redeploying the previous binaries or container image? A: No. Starting a process on an older version against a migrated schema is not a supported operation, because migrations can alter configuration data as well as schema structure. Note that outdated nodes which are already running against a migrated schema are fine, as that is a required part of an online upgrade; the distinction is between continuing to run an outdated process and starting one. See Rolling Back an Online Upgrade.
Q: Is there a zero-downtime rollback path? A: No. The supported way to revert an upgrade is to restore your pre-upgrade database backups, which requires a full cluster outage. Plan your upgrade on the basis that rolling forward is the recovery path.
Q: What's the recommended upgrade path for systems more than two major releases behind? A: If you are able to sustain cluster downtime, perform a one-time offline mode upgrade. If not, perform a series of two-version online mode upgrades.
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.