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

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 [email protected]

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.1 to v1.3 without first upgrading to v1.2 for example.

Are you just upgrading from v1.3* to a newer hotfix than the incompatible v1.3.1? If so, you follow step 2 and step 3 then use the new version in your deploy scripts. Running Ansible changes and data migrations are not required on any hotfix release.

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?

As of OpenCRVS 1.2* we have a new integrations UI and a migration to move existing integrations over. But we have also refactored the folder structure of our country configuration server considerably. We recommend that you migrate on a Quality Assurance or Staging server and test that your migrations work in a test environment first. Reach out to us if you need help.

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: Update locally and on a QA server

We have worked hard to ensure that migrating from v1.3 to v1.3.* 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 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

git pull

yarn --force

2. You will now have the release 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>

4. Ensure that the branches you have set up are ready according to the new forking instructions here. Specifically from step 9 to 17.

5. Fetch all our latest branches as step 17 will have added countryconfig as a remote:

git fetch --all

6. 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-v1.3.<insert version>

git merge countryconfig/master

yarn --force

7. You will likely need to fix some conflicts.

8. 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. When you are satisfied, merge your PR.

2. Tag, build and publish a release image for your upgrade. You can use our supplied Github Action for this: https://github.com/opencrvs/opencrvs-countryconfig/blob/master/.github/workflows/publish-release.yml

3. Ensure that you have any new required environment variables that are required in v1.3.1 such as CONTENT_SECURITY_POLICY_WILDCARD

4. Deploy to your QA server using the updated version tag

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: make an emergency backup of your data before proceeding so that you can restore in the event of any migration problems. THIS BACKUP MUST BE STORED EXTERNALLY FROM YOUR PRODUCTION SERVER BEFORE PROCEEDING. THIS BACKUP MUST BE RESTORED SUCCESSFULLY ON A QUALITY ASSURANCE / STAGING / TEST SERVER TO ENSURE IT WORKS BEFORE CONTINUING.

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 an option could be to temporarily cease civil registration operations, then perform an upgrade on an entirely new set of servers that have been restored wth a backup performed at the point when operations ceased. When you have tested your migrated servers and data, you can then change your DNS settings to point to your new server and resume operations with confidence.

1. Deploy to your Production server using the updated version tag once you have satisfied yourself that you are backed up according to the warnings above.