# v1.3.\* to v1.3.\* Migration notes ### Step 1: Prepare to migrate {% hint style="warning" %} 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 [team@opencrvs.org](mailto:team@opencrvs.org?subject:WebsiteEnquiry) {% endhint %} 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? {% hint style="info" %} It is not possible to upgrade from v1.1 to v1.3 without first upgrading to v1.2 for example. {% endhint %} {% hint style="warning" %} **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. {% endhint %} 3\. Have you made any NodeJS or React code customisations of any kind to opencrvs-core? {% hint style="info" %} 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. {% endhint %} 4\. Have you integrated OpenCRVS to another system using an API, or documented system client? {% hint style="info" %} 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. {% endhint %} 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? {% hint style="info" %} 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](https://documentation.opencrvs.org/v1.4/general/releases/broken-reference). 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. {% endhint %} ### 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**](https://git-scm.com/docs/git-merge) **or** [**Git rebase**](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase)**)**. Please refer to the [release notes](https://documentation.opencrvs.org/v1.4/general/releases/v1.1.0-release-notes) and our [release process including Gitflow](https://documentation.opencrvs.org/v1.4/general/releases) branching approach. {% hint style="info" %} Replace the \* with the latest minor hotfix release in all the following steps. {% endhint %} 1. Navigate to your opencrvs-core directory, checkout the **master** branch and pull latest changes. Yarn install any dependency upgrades: ``` cd /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 /opencrvs- ``` 4\. Ensure that the branches you have set up are ready according to the new forking instructions [here](https://documentation.opencrvs.org/v1.4/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.1-fork-your-own-country-configuration-repository). Specifically from [step 9 to 17](https://documentation.opencrvs.org/v1.4/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.1-fork-your-own-country-configuration-repository). 5\. Fetch all our latest branches as [**step 17 will have added countryconfig as a remote**](https://documentation.opencrvs.org/v1.4/setup/3.-installation/3.2-set-up-your-own-country-configuration/3.2.1-fork-your-own-country-configuration-repository): ``` git fetch --all ``` 6\. Create a new branch for a PR that will be a merge or rebase from our release. {% hint style="info" %} **It is generally easier to**[ **merge than rebase (advanced)**](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)**.** {% endhint %} ``` git checkout -b upgrade-countryconfig-v1.3. ``` ``` 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](https://documentation.opencrvs.org/v1.4/setup/3.-installation/3.1-set-up-a-development-environment/3.1.3-starting-and-stopping-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. 9. When you are satisfied, merge your PR. 10. 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**](https://github.com/opencrvs/opencrvs-countryconfig/blob/master/.github/workflows/publish-release.yml) 11. Ensure that you have any new required environment variables that are required in v1.3.1 such as CONTENT\_SECURITY\_POLICY\_WILDCARD 12. 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: {% hint style="danger" %} 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**](https://documentation.opencrvs.org/v1.4/general/releases/broken-reference) 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.** {% endhint %} {% hint style="danger" %} 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. {% endhint %} {% hint style="danger" %} 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. {% endhint %} 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.