OpenCRVS
v1.3
v1.3
  • 👋Introduction
  • Product Specifications
    • Functional Architecture
    • Workflow management
    • Status Flow Diagram
    • Users
      • Examples
    • Core functions
      • 1. Notify event
      • 2. Declare event
      • 3. Validate event
      • 4. Register event
      • 5. Print certificate
      • 5. Issue certificate
      • 6. Search for a record
      • 7. View record
      • 8. Correct record
      • 9. Verify record
      • 10. Archive record
      • 11. Vital statistics export
    • Support functions
      • 10. Login
      • 11. Audit
      • 12. Deduplication
      • 13. Performance management
      • 14. Payment
      • 15. Learning
      • 16. User support
    • Admin functions
      • 17. User management
      • 18. Comms management
      • 19. Content management
      • 20. Config management
    • Data functions
      • 21. Legacy data import
      • 22. Legacy paper import
  • Technology
    • Architecture
      • Performance tests
    • Standards
      • FHIR Documents
        • Event Composition
        • Person
        • Registration Task
        • Event Observations
        • Locations
    • Security
    • Interoperability
      • Create a client
      • Authenticate a client
      • Event Notification clients
      • Record Search clients
      • Webhook clients
      • National ID client
      • FHIR Location REST API
      • Other ways to interoperate
  • Default configuration
    • Intro to Farajaland
    • Civil registration in Farajaland
    • OpenCRVS configuration in Farajaland
      • User / role mapping
      • Application settings
      • Declaration forms
      • Certificate templates
    • Business process flows in Farajaland
  • Setup
    • 1. Establish team
    • 2. Gather requirements
    • 3. Installation
      • 3.1 Set-up a local development environment
        • 3.1.1 Install the required dependencies
        • 3.1.2 Install OpenCRVS locally
        • 3.1.3 Starting and stopping OpenCRVS
        • 3.1.4 Log in to OpenCRVS locally
        • 3.1.5 Tooling
      • 3.2 Set-up your own country configuration
        • 3.2.1 Fork your own country configuration repository
        • 3.2.2 Set up administrative address divisions
          • 3.2.2.1 Prepare source file for administrative structure
          • 3.2.2.2 Prepare source file for statistics
        • 3.2.3 Set up CR offices and Health facilities
          • 3.2.3.1 Prepare source file for CRVS Office facilities
          • 3.2.3.2 Prepare source file for health facilities
        • 3.2.4 Set up employees & roles for testing or production
          • 3.2.3.1 Prepare source file for employees
          • 3.2.3.2 Configure role titles
        • 3.2.5 Set up application settings
          • 3.2.5.1 Configuring Metabase Dashboards
        • 3.2.6 Configure certificate templates
        • 3.2.7 Configure declaration forms
          • 3.2.7.1 Configuring an event form
        • 3.2.8 Seeding your local development environment database
          • 3.2.8.1 Clearing your local development environment database
        • 3.2.9 Countryconfig APIs explained
          • 3.2.9.1 Managing language content
      • 3.3 Set-up a server-hosted environment
        • 3.3.1 Provision your server nodes with SSH access
        • 3.3.2 Provision environment
        • 3.3.3 Provision a comms gateway
        • 3.3.4 Set up an SMTP server for OpenCRVS monitoring alerts
        • 3.3.5 Setup DNS A records
        • 3.3.6 Deploy (Automated & Manual)
        • 3.3.7 Seeding & clearing data on a server
        • 3.3.8 Automated & manual backup and manual restore
    • 4. Functional configuration
      • 4.1 Configure application settings
      • 4.2 Configure registration periods and fees
      • 4.3 Create new user roles
      • 4.4 Managing system users
    • 5. Testing
    • 6. Go-live
    • 7. Monitoring
      • 7.1 Application logs
      • 7.2 Infrastructure health
      • 7.3 Routine monitoring checklist
      • 7.4 Setting up alerts
      • 7.5 Managing a Docker Swarm
  • General
    • Contributing
    • Releases
      • v1.3.5: Release notes
      • v1.3.4: Release notes
      • v1.3.2: Release notes
      • v1.3.1: Release notes
      • v1.3.* to v1.3.* Migration notes
      • v1.3.0: Release notes
      • v1.2.* to v1.3.* Migration notes
        • v1.2 to v1.3: Form migration
      • v1.2.1: Release notes
      • Patch: Elasticsearch 7.10.2
      • v1.2.0: Release notes
      • v1.1.* to v1.2.* Migration notes
      • v.1.1.2: Release notes
      • v.1.1.1: Release notes
      • v1.1.0: Release notes
    • Interoperability roadmap
    • Product roadmap
Powered by GitBook
On this page
  • Step 1: Prepare to migrate
  • Step 2: Convert your OpenCRVS 1.2 form configuration
  • Step 3: Upgrade your code
  • Step 4: Upgrade your server environments
  1. General
  2. Releases

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

Previousv1.3.0: Release notesNextv1.2 to v1.3: Form migration

Last updated 1 year ago

Are you just upgrading from v1.3* to a newer hotfix, e.g.: v1.3.1? If so, just use the new version in your deploy scripts.

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

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.

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.3* we have 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?

Step 2: Convert your OpenCRVS 1.2 form configuration

One of the biggest architectural changes we have made in OpenCRVS 1.3, was the difficult decision to deprecate the form configuration UI that we introduced in 1.0.

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

or 

git checkout master (Always aligned to the latest release)
git pull
yarn --force

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

cd <path on your environment>/opencrvs-<your country>

Refer to our release notes in order to understand breaking changes

Step 4: Upgrade your server environments

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

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

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

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

In OpenCRVS v1.3.* 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.3.* servers that have been restored wth a v.1.2* 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.2* OpenCRVS on a server, and you have a successful restoration from a v1.2* 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. Check you can login to OpenCRVS v1.3 successfully.

  3. You can then login to OpenCRVS v1.3.* and test that all your data has migrated successfully.

We ask these questions to make sure that you are aware that you should . 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.

Please refer to

4. Ensure that the branches you have set up are ready according to your strategy explained . Pull, fix conflicts, merge and test according to your strategy.

5. If you are running OpenCRVS locally, simply . 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.

If you have hosted AND CONFIGURED OpenCRVS on a server and are capturing live registrations in production, YOU MUST: 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.

Configure a new set of v1.3.* servers following ALL the to .

Deploy v1.3* following the including the new secrets

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

team@opencrvs.org
backup your data first and ensure that you can restore from a backup
form migration instructions.
here
start OpenCRVS
make an emergency backup of your data before proceeding
steps 3.3.1
3.3.5
new deploy instructions
steps