Version upgrades

Step-by-step guide for upgrading the version of your OpenCRVS deployment

Notice: This guide applies only to upgrading from v1.9 onwards.

If you are running OpenCRVS v1.8 or earlier, follow the v1.9 migration guide instead.

Introduction

OpenCRVS supports incremental upgrades between versions. However, careful preparation is essential — especially for governments operating live civil registration systems.

This guide walks you through planning, testing, and safely upgrading to a newer version of OpenCRVS.

Upgrades impact your infrastructure, data, integrations, and users. Following this structured process helps minimise risk and ensures a smooth transition.

Critical requirement — OpenCRVS supports upgrading one major/minor version at a time. For example: v1.9.x → v2.0.x → v2.1.x (not v1.9 → v2.1 directly).

Need help? Contact us at [email protected].

---

Upgrade process

This guide outlines a step-by-step process for safely upgrading OpenCRVS. Each step builds on the previous one and must be completed in sequence.

The process progresses through environments of increasing importance — local development, QA, staging, and finally production. This staged approach ensures issues are identified and resolved before affecting live systems.

The upgrade process consists of 7 steps:

1

Preparation

Review your current setup, customisations, and readiness.

2

Update code and test locally

Update core and country configuration code, test locally, and commit changes.

3

Update GitHub environments

Update GitHub secrets and environment variables.

4

Deploy to QA environment

Deploy and test the new version in QA.

5

Deploy to staging environment

Deploy and validate using production-like data.

6

Schedule downtime and notify staff

Prepare users and pause operations safely.

7

Deploy to production

Run the upgrade in production and resume operations.

---

Step 1 — Preparation

Before upgrading, review the following areas. These are the same considerations used during implementation support, as they directly affect upgrade complexity.

Version analysis

• Which version of OpenCRVS are you currently running?

• Which version are you upgrading to?

Core code customizations

• Have you modified opencrvs-core (Node.js, React, or API logic)?

• Are you maintaining a fork of opencrvs-core?

Important — If you maintain a fork, you must merge or rebase it with opencrvs/opencrvs-core.

We strongly recommend contributing changes upstream instead of maintaining long-lived forks.

External integrations

• Have you integrated OpenCRVS with external systems (e.g. population registers, ID systems, HIS, notification services)?

All integrations must be retested after upgrading.

Country configuration status

• Is your country configuration fully complete? I.e. have you gone through all the steps on Configuration

Staff readiness

• Are real users actively using the system?

• Will they require training for new workflows or UI changes?

Data considerations

• Are you already registering real citizens?

• Do you have reliable backups and a working staging database restore pipeline?

Infrastructure checks

If deployed to servers, confirm:

• Are you using Docker Swarm or Kubernetes?

• Do you have dedicated or shared infrastructure?

• What are your environments (dev, QA, staging, production)?

• What are your automated backup and restore processes?

• Do you have sufficient RAM, disk space, and CPU capacity? <TODO: Link to correct place on docs>

• What is the cluster size (1, 3, or 5 nodes — all nodes must be reprovisioned) <TODO: Link to correct place on docs>

These checks ensure your infrastructure is healthy, backups are reliable, and upgrades can safely be tested before production deployment.

Step 2 — Update code and test locally

The complexity of this step depends on the level of customisation in your country configuration.

Update opencrvs-core

cd <path>/opencrvs-core
git fetch
git checkout release-v*.*.*
git pull
yarn --force

You now have the target OpenCRVS release code locally.

Update your country configuration fork

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

## Ensure upstream points to opencrvs/infrastructure
git remote -v

git fetch --all

## Create a temporary upgrade branch
git checkout -b upgrade-v<target-version>

## Upgrade the toolkit package version to the target version
yarn add @opencrvs/[email protected] --exact

## Run codemod tool, which upgrades your countryconfig to support v2.0
## If you are still on Docker Swarm (instead of kubernetes), use the --docker-swarm flag!
## If this flag is set, the /infrastructure directory is kept.
## Otherwise it is deleted in favour of a separate infrastucture repository.
yarn opencrvs upgrade [--docker-swarm]

## At this point you might run in to merge conflicts under the /infrastructure directory.
## Now is the time to fix these!

## Update npm dependencies
yarn --force

## Finally, we recommend autoformatting your code
yarn prettier --write src/ infrastructure/

Run locally

Start OpenCRVS locally. Database migrations will run automatically.

Test thoroughly

Verify all key flows, integrations, and customisations before proceeding.

Updating infrastructure repository (only for users on kubernetes)

Infrastructure-repository is only used for kubernetes deployments, skip this if you are on docker-swarm!

cd <path>/opencrvs-<your-country>-infrastructure

## Ensure upstream points to opencrvs/infrastructure
git remote -v

git fetch --all

## Create a temporary upgrade branch
git checkout -b upgrade-v<target-version>

## Upgrade the toolkit package version to the target version
git merge upstream/release-v2.x.x

Commit and push

• Create a pull request for review

• Merge into your main branch

A new Docker image will be automatically built and pushed.

Step 3 — Update GitHub environments

Back up all existing secrets and variables before making changes.

Each release may introduce:

• New secrets

• Renamed or removed variables

• DevOps improvements

To upgrade your environment details:

## IF on docker swarm
cd <path>/opencrvs-<your-country>

## IF on kubernetes
cd <path>/opencrvs-<your-country>-infrastructure

yarn environment:init

The script will:

• Prompt for missing secrets

• Generate new values where required

• Ask before overwriting existing values (do not overwrite production secrets)

Step 4 — Deploy to QA environment

1. Run the Provision GitHub Action:

   1. Go to Actions in your repository

   2. Select Provision workflow

   3. Click Run workflow

   4. Choose 'qa' as 'Machine to provision'

   5. Click Run workflow

2. Run Deploy GitHub Action using:

   • New opencrvs-core release version

   • The new countryconfig Docker image git hash

3. Do not reset the environment (migrations run automatically)

Monitor migrations in Kibana using: tag: migration

Test your new QA deployment before proceeding!

Step 5 — Deploy to staging environment

Repeat the steps used for QA, but for staging environment:

1. Provision

2. Deploy

Monitor migrations in Observability → Logs using tag: migration.

Do not use the deployment until migrations complete. Then perform full validation with your QA team.

Because staging contains real citizen data (from production backups), migrations may take hours.

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.

Ensure backups are working and can be restored to staging. Keep an offline and online copies of recent backups in case recovery is needed. Read the backup instructions.

Step 6 — Schedule downtime and notify staff

Browser caches are cleared during upgrades. Any unsubmitted drafts stored locally will be permanently lost.

Use Email All Users to instruct staff to:

• Stop work before the upgrade

• Submit all offline drafts

• Ensure their outbox is empty

Step 7 — Deploy to production

Never upgrade production without successfully restoring a backup to staging first.

Pre-upgrade checklist:

• Ensure backups restore correctly on staging

• Maintain a hard copy of recent backups

• Expect database migrations to take hours

• Expect reduced system performance during migration

• Never upgrade production without validating on staging first

Upgrade steps

1. Provision Backup server

2. Provision Production server

3. Deploy using the new release and countryconfig image

4. Monitor migrations in Kibana (tag: migration)

5. Do not use production until migration finishes

6. Log in and test with your QA team

7. Notify staff that operations can resume