v1.3.* to v1.4.* Migration notes

The changes in 1.4.0 are all to do with DevOps and infrastructure, improving security in many ways.

The best thing to do is to read the entire section 3.3 Set-up a server hosted environment again before planning how best to upgrade and migrate your code.

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 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?

It is not possible to upgrade from v1.2 to v1.4 without first upgrading to v1.3 for example.

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?

5. Have you completely configured OpenCRVS?

6. Have you setup real registrar users in the system?

7. Are you already registering real citizens in testing or production?

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 emergency 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 / staging / test 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: Read the new documentation on server hosted environments

The changes in 1.4.0 are all to do with DevOps and infrastructure improving security in many ways.

The best thing to do is to read the entire section 3.3 Set-up a server hosted environment again before planning how best to upgrade and migrate your code.

Step 3: Upgrade your code

The next task requires you to pull latest changes in core and our countryconfig repository, resolve conflicts in your countryconfig repository and merge.

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

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

2. You will now have the core release code. Your next step is to pull countryconfig release code.

3. Navigate to your forked country configuration repo

4. Checkout the release-v1.4.0 or master branch and pull latest changes from our repo into a branch that is dedicated for this upgrade.

5. Fix conflicts, merge and test according to your strategy.

Refer to our release notes in order to understand breaking changes

Step 4: Upgrade your server environments

If you have hosted AND CONFIGURED OpenCRVS on a server and are capturing live registrations in production, YOU MUST: make a backup of your data before proceeding so that you can restore in the event of any migration problems. THIS BACKUP MUST BE DOWNLOADED, SO YOU HAVE A 2ND COPY STORED EXTERNALLY FROM YOUR SERVER BEFORE PROCEEDING. THIS BACKUP MUST BE RESTORED SUCCESSFULLY ON A QUALITY ASSURANCE / STAGING / TEST SERVER TO ENSURE IT WORKS BEFORE CONTINUING.

The cleanest approach for upgrading server environments is to provision an entirely new set of servers and then restore your back up onto them.

Follow all the steps in 3.3 Set-up a server hosted environment.

Step 4: Upgrade your server environments

Follow the documentaion in 3.3 Set-up a server hosted environment

When your new servers are running with your restored backup, login to Kibana, and visit Observability > Logs. Search for the migration microsevice logs like this:

tag: migration

You want to check that any database migrations ran successfully and that there were no errors.