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

Are you just upgrading from v1.2* to a newer hotfix than the incompatible v1.2.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: Begin the migration locally on your computer first

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

As of December 2022 the latest release is: v1.2.0-beta

Step 3: Upgrade your code

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

cd <path on your environment>/opencrvs-core

git fetch

git checkout release-v1.2.0

or 

git checkout master (Always aligned to the latest release)

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.

If you have made no customisations to the Farajaland country configuration, other than updating your csv files for administrative divisions, offices and health facilities, employees and created new backups, the merge or rebase process should be easy. If you have customised any routes or developed new API integrations, you may need to be a bit more careful with merging conflicts.

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

git fetch --all

6. Checkout your master-<your country code> branch, and merge or rebase from our release.

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

Merge/Rebase note: Prioritise your current backup zip files over our incoming Farajaland backups otherwise you will need to regenerate your backups after the process ends. Prioritise incoming changes for any other conflicts and refactor your code if you have developed your own customisations. Refer to our release notes for hints and any new translation keys that you will need to fix conflicts for.

git checkout master-<your country alpha3 code>

git merge farajaland/release-v1.2.0

or 

git merge farajaland/master  (Always aligned to the latest release)

yarn --force

7. (Optional: if you are actively developing new features in your country configuration) Checkout and merge your master-<your country code> branch onto any other Git branches that are appropriate to you such as develop-<your country code> . Then checkout back to your master-<your country code> branch before proceeding!

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.

Step 4: Upgrade your server environments

THESE NOTES ARE FOR USERS MIGRATING FROM v1.1.* to v1.2.* ONLY!!!!

Before you commence, ensure that you have understood these warning operational steps:

Warning 1: Backup and test a restore of your v1.1* data on a new v1.1.* test server

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

Warning 2: Prepare operationally for a v1.2.* migration. Test the following steps on a test server first. Schedule the production migration when staff can cease operations.

In OpenCRVS v1.2.* we have some large data migrations to run. 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. This will lead to reduced performance of OpenCRVS during this time. Therefore we recommend performing a data migration on an entirely new set of v1.2.* servers that have been restored wth a v.1.1.* backup created in Warning 1. When you have tested your migrated servers and data, you can then change your DNS settings to point to your new server with confidence. COMPLETE A MIGRATION ON A TEST SERVER BEFORE RUNNING ON PRODUCTION. CEASE CIVIL REGISTRATION ACTIVITIES DURING A PRODUCTION MIGRATION. CONSIDER PERFORMING A PRODUCTION MIGRATION DURING NATIONAL HOLIDAYS TO AVOID RISK OF DATA LOSS.

1. If you have hosted an entirely new v1.1* OpenCRVS on a server, and you have a successful restoration from a v1.1* backup running on this server, and you have a 2nd copy of the backup of your configuration hosted elsewhere just in case, you are ready to proceed.

2. Configure a new set of v1.2.* servers following ALL the steps 3.3.1 to 3.3.5.

In step 3.3.5, if you configured your DNS settings with a wilcard, e.g. *.<your_domain> then you can continue to the next step. Otherwise in OpenCRVS v1.2* we have introduced the following new subdomains, so you must create A records for them.

documents.<your_domain>

minio.<your_domain>

minio-console.<your_domain>

ui-kit.<your_domain> (previously styleguide.<your_domain>)

3. Deploy v1.2* following the new deploy instructions including the new secrets MINIO_ROOT_USER and MINIO_ROOT_PASSWORD and a default set of your country configuration factory reset backups.

4. Check you can login to OpenCRVS v1.2 successfully.

5. Check that you can login to the Minio console using your MINIO_ROOT_USER and MINIO_ROOT_PASSWORD at: https://minio-console.<your_domain>

6. OpenCRVS v1.2 is successfully installed, so now we must empty the database and restore it with your v1.1* data. Follow these manual restore process using these steps.

7. You can login to OpenCRVS v1.2.* and test that all your data has migrated successfully. Look at a registration that had previously attached supporting documentation, and you will notice that the documents are now served from Minio.