OpenCRVS Docs 1.1

v1.0.1 to v1.1.* Migration notes

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]
We have worked hard to ensure that migrating from v1.0 to v1.1.* 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 rebase it. (You must be familiar with the concept of Git rebase). Please refer to the release notes and our release process including Gitflow branching approach.
Replace the * with the latest minor hotfix release.
As of November 2022 the latest release is: v1.1.2

Step 1: Upgrade your code

  1. 1.
    Navigate to your opencrvs-core directory, checkout the release-v1.1.0 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.1.*
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 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 for rebasing 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 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 rebase from our release. (You must be familiar with the concept of Git rebase). Yarn install any dependency upgrades.
Rebase note: Prioritise your current backup zip files over our incoming Farajaland backups otherwise you will need to regenerate your backups after the rebase 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 rebase farajaland/release-v1.1.*
git rebase farajaland/master (Always aligned to the latest release)
yarn --force
7. (Optional) Checkout and rebase your master-<your country code> branch onto any downstream Gitflow branches that are appropriate to you such as develop-<your country code> . Then checkout back to your master-<your country code> branch before proceeding!

Step 2: Upgrade your environments

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.
DO NOT USE ANY ANSIBLE PLAYBOOK BELOW v1.1.2 OR YOU COULD LOSE DATA. If you have customised our Ansible playbook you must carefully copy over your customisations into the v1.1.2 playbook and make a new cusomised playbook. Note that the v1.1.2 playbook also imports a playbook in the country configuration repo.
If you have hosted OpenCRVS on a server, and you have a backup of your configuration, you must run the Ansible scripts again depending on your set up. You run these scripts from the opencrvs-core master branch inside the infrastructure/server-setup folder.
cd <path on your environment>/opencrvs-core/infrastructure/server-setup
ansible-playbook -i <inventory_file> <playbook_file> -e " \
dockerhub_username=<your dockerhub username> \
dockerhub_password=<your dockerhub password> \
mongodb_admin_username=<mongo username> \
mongodb_admin_password=<mongo password you generated> \
elasticsearch_superuser_password=<elastic password you generated> \
disk_encryption_key=<a strong disk encryption password> \
country_config_path=<local path to your country config folder> \

Step 3: Deploy or run your local environment

  1. 1.
    If you have hosted OpenCRVS on a server, build your country configuration Docker image and deploy using the tag v1.1.* for your core image. Migrations will automatically run on your data.
  2. 2.
    If you are running OpenCRVS locally, simply start OpenCRVS. Migrations will automatically run on your data.
You can check if your Migrations have run successfully in Kibana.

Known issues

  1. 1.
    Deployment script: We deprecated the --update-metadata parameter which is passed to from the Github Deploy Action. The country configuration Github Action file deploy.yml still attempts to pass this parameter to This causes the deploy script to fail. To resolve this issue, please edit the Github Action deploy.yml in your country configuration in lines 90, 112 and 134 from:
bash --clear-data=${{ env.FACTORY_RESET }} --restore-metadata=${{ env.FACTORY_RESET }} --update-metadata=no ...
bash --clear-data=${{ env.FACTORY_RESET }} --restore-metadata=${{ env.FACTORY_RESET }} ...