5.5.1Version-Specific upgrade concerns

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.

2019.08.R01
2020.02.R01
2020.11.R01
2021.02.R05
2023.02.R01
2024.02.R01

5.5.1.12019.08.R01

5.5.1.1.1Subscriptions

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.

5.5.1.22020.02.R01

5.5.1.2.1Clustering Redesign

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

5.5.1.32020.11.R01

5.5.1.3.1Addition of Automatic Upgrade On Boot

In this version, automatic upgrade at boot was introduced via the update_mode property. This upgrade method is no longer recommended.

5.5.1.42021.02.R05

5.5.1.4.1Online Mode Upgrade

online mode upgrades were added as a concept in this version. Versions before this are not able to take advantage of online upgrades.

5.5.1.52023.02.R01

5.5.1.5.1Upgrade Docker Container to non-root

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:

When upgrading from releases before 2023.02.R01 to a release on or after 2023.02.R01
Create or use an existing non-root user to run the container, e.g. smile
Log on as that user
Change the ownership of any container volume directories. The original volume mounts were created and owned by root and must be changed to the new $USER so the new user can write to them.

sudo chown -R $USER /path/to/volume-mount

Perform the upgrade as usual Docker Container Installation

5.5.1.62024.02.R01

5.5.1.6.1Addition of CDR_UPGRADE_MODE property

Usage of the CDR_UPGRADE_MODE system property is available from this version onwards.

5.5.2Frequently Asked Questions

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: Use your pre-upgrade backups to restore the system to its previous state. Contact Smile Digital Health support for assistance.

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.

5.4 Database Migration Impact