v1.4.0 to v1.4.1 Migration notes

The breaking change between v1.4.0 and v1.4.1 is that the JSON files for language content in the "login", "client" & SMS "notification" copy have been replaced by CSV files. This is so that copy would be easily editable in software like Excel and Google Sheets. After this change, AVAILABLE_LANGUAGES_SELECT doesn't need to be defined anymore by country config.

When you pull latest changes from the countryconfig remote release-v1.4.1 branch, you will notice (modify/delete) warnings on the login.json, client.json and notification.json files. These are no longer required. You can delete them once you have copied over the text into the CSV file explained below.

Instead you will notice 3 new files in the src/translations directory.

Copy over the copy and translations from the JSON into the new CSV format.

Updated instructions are documented in the section: 4.2.5.1 Managing language content

Our usual migration guide follows for countries with active OpenCRVS installations ...

Step 1: Prepare to migrate

If you are working on behalf of a government that is considering implementing OpenCRVS, we can help you to migrate your version of OpenCRVS.

Please contact us at [e-mail]

Before you start migrating, consider these questions and the potential impacts of upgrading, which we would ask you if we were offering support:

1. What version number you are currently using?

2. What version number you wish to upgrade to?

3. Have you made any NodeJS or React code customisations of any kind to opencrvs-core?

Some people make customisations to opencrvs-core which means they need to merge or rebase changes to core as well as the country configuration server. Normally we do not advise people to make their own core customisations but instead work with our core team to open pull requests on core for any functionality you need. However some people choose to do this independently, so make sure you also merge/rebase your core repo too.

4. Have you integrated OpenCRVS to another system using an API, or documented system client? Remember to schedule and QAany integrations after updating.

5. Have you completely configured OpenCRVS? Conflicts in our countryconfig repo may not apply to your configuration.

6. Have you setup real registrar users in the system? Do they need to be trained on any new business processes?

7. Are you already registering real citizens in testing or production? Do you have a backup and staging environment to ensure that citizen data is backed up successfully before you start?

8. Have you deployed OpenCRVS to a server environment? If so, answer these additional questions:

• Please tell us if you have dedicated or shared servers

• Do you have independent development (staging), quality assurance and production servers? Tell us what you have.

• What are the specifications of your servers?

• Are you running OpenCRVS on a cluster of 1, 3 or 5 servers?

• Have you provisioned a backup server and automated staging backups as documented?

• How much free disk space and RAM is generally available on each server?

We ask these questions to make sure that you are aware that you should backup your data first and ensure that you can restore from a backup. We ask them to make sure you have healthy environments with enough RAM and disk space. You must test your migration first on a dedicated quality assurance and staging server before attempting to migrate a production server. You need to know that your configurations still work and your data is safe. If you have concerns, reach out to us for support.

Step 2: Update locally and on a QA server

We have worked hard to ensure that migrating from v1.4 to v1.4.* is as easy as possible. The most complex task really depends upon how much customisation you have made to your country configuration fork as you will be required to merge or rebase your fork with our release branch. (You must be familiar with the concept of Git merge or Git rebase).

Please refer to the release notes , which contains a video of an example code upgrade process, and our release process including Gitflow branching approach.

Replace the * with the latest minor hotfix release in all the following steps.

1. Navigate to your opencrvs-core directory, checkout the master branch and pull latest changes. Yarn install any dependency upgrades:

cd <path on your environment>/opencrvs-core

git fetch

git checkout master 

or, alternatively checkout the release branch of choice, if master has moved on

git checkout release-v*.*.* <-- substitute version of choice!

git pull

yarn --force

2. You will now have the release opencrvs-core code locally to run alongside your updated countryconfig code. Your next step is to merge or rebase any changes you need from the country configuration repository fork.

3. Navigate to your forked country configuration repo

cd <path on your environment>/opencrvs-<your country>

git fetch --all

4. Create a new branch for a PR that will be a merge or rebase from our release.

It is generally easier to merge than rebase (advanced).

git checkout -b upgrade-countryconfig-v<insert new version>

The following command pulls from a remote named "upstream" which should point to our countryconfig repository as documented here.

git pull upstream release-v*.*.* <-- substitute version of choice!

yarn --force

5. You will likely need to fix some conflicts.

6. If you are running OpenCRVS locally, simply start OpenCRVS. Migrations will automatically run on your data and you have finished upgrading OpenCRVS locally. Proceed to the next section if you have already deployed OpenCRVS to a remote server cluster.

1. Commit and push your changes to a pull request for peer review.

2. When you are satisfied, merge your PR.

3. Tag, build and publish a release image for your upgrade. You can use our supplied Github Actions

4. Deploy to your QA server using the updated version tag and quality assure your release before proceeding.

Step 3: Upgrade your production server environments

Before you commence, ensure that you have understood these warnings:

If you have hosted AND CONFIGURED OpenCRVS on a server and are capturing live registrations in production, YOU MUST ENSURE THAT OPENCRVS BACKUPS ARE WORKING AND RESTORING ON A "STAGING" ENVIRONMENT. This is so that you can restore in the event of any migration problems.

All un-submitted draft applications only exist locally in a users browser cache and are therefore not preserved when the application is updated. The browser cache is cleared. Inform all staff to submit in-progress drafts before updating OpenCRVS in production.

A release of OpenCRVS can contain automatic database migrations. If you have been running OpenCRVS in production and you have live civil registrations for real citizens, these migrations may take several hours to complete depending on your scale. This will lead to reduced performance of OpenCRVS during this time. Therefore test your release on a "staging" environment first that has a restored backup of citizen data on it. Monitor migrations in Kibana, searching Observability > Logs using "tag: migration" to ensure there are no migration errors.

Deploy to your Production server using the updated version tag once you have satisfied yourself that you are backed up, and that migrations run smoothly, according to the warnings above.