OpenCRVS

A digital public good for civil registration
Report an issue · Case studies · Implementations · About us

• OpenCRVS
• Important! Please read
• Install dependencies
• Install OpenCRVS
• Log into OpenCRVS
  • Field Agent
  • Registration Agent
  • Registrar
  • Local System Admin
  • National System Admin
• Starting and stopping OpenCRVS
  • Starting
  • Stopping
• Other servers
  • React Storybook
  • OpenHIM
• Configuring OpenCRVS
• What are the key OpenSource dependencies of OpenCRVS?
  • Hearth MongoDB Database layer
  • ElasticSearch
  • InfluxData
  • OpenHIM enterprise service bus, interoperability Layer
• What is inside the OpenCRVS packages?
  • OpenCRVS microservice business layer packages
  • OpenCRVS client application packages
  • OpenCRVS component library package
  • OpenCRVS performance testing packages
  • What automated testing support is there?
• Become part of the OpenCRVS Community
• Contributing
  • How to tag an OpenCRVS release?
• License

OpenCRVS

OpenCRVS (Civil registration & Vital Statistics) is a digital public good to help achieve universal civil registration and evidence-based decision making in all country contexts.

We are on a mission to ensure that every individual on the planet is recognised, protected and provided for from birth.

Important! Please read

The following instructions will guide you on how to set up a local, demo development environment of OpenCRVS using our fictional country configuration: "Farajaland".

In order to run OpenCRVS, we expect that you have a working knowledge of Linux / Unix operating systems and can run terminal commands.

OpenCRVS consists of multiple servers which run in Docker containers and requires Node JS. You should be familiar with the concepts of Docker and Node JS web application software development.

Install the dependencies and follow the first time setup instructions. This will checkout, download, install, configure and start all the servers for you in order to get up and running quickly with OpenCRVS.

Read review our documentation before going further.

Install dependencies

Dependencies are required. Ensure you have satisfied all the following requirements before continuing:

• Operation system: Linux or Unix operating system is required: e.g. Ubuntu or Mac OSX: If you do not have Ubuntu or MacOSX, investigate installing a virtual Ubuntu environment on your computer.
• Disk space and RAM: A minimum of 10GB of hard drive space available and at least 8GB of RAM. If you are using virtualisation, ensure this is dedicated to the environment.
• Docker: On Ubuntu, install Docker & Docker Compose. On Mac, install Docker for Mac. On Mac, in Docker for Mac preferences, assign 4 CPUs, at least 8GB Memory or more, Swap 4GB and 4 CPUs if your system allows. Elastic search needs a lot of memory to run. On Ubuntu we set enough RAM automatically.
• Nodejs: Install Node v.14.15.0, v14.15.4, 14.17.0 or v14.18.1 (this release has been tested on those versions). You can manage the Node version of your choice using Node Version Manager.
• Yarn: Install the Yarn Package Manager for Node
• Chrome: Install Google Chrome. The OpenCRVS client application is a progressive web application.
• tmux: Install tmux. Multiple terminal windows are required to run OpenCRVS Core alongside the default country configuration. On Ubuntu run: sudo apt-get install tmux to install. On Mac, you can install tmux using Homebrew or MacPorts.

Install OpenCRVS

The following instructions will guide you on how to set up a local, demo development environment of OpenCRVS using our fictional country configuration: "Farajaland". To deploy OpenCRVS onto a publicly accessible server, follow these instructions.

1. Check you have installed all the dependencies. See above.

2. Run git clone https://github.com/opencrvs/opencrvs-core.git

3. Run cd opencrvs-core

4. Run git checkout master

5. Run bash setup.sh (takes 10-15 minutes)

   This installer script will:

   • Tests your dependencies
   • Checks that required ports are available. NOTE: MacOS Monterey runs AirPlay on port 5000. Mac Monterey users need to disable AirPlay in System Preferences in order to run OpenCRVS.
   • Download and install all Docker images
   • Check out the example OpenCRVS country configuration
   • Runs all OpenCRVS Core microservices
   • Run the OpenCRVS fictional country configuration, "Farajaland" and populate local databases with Farajaland reference data
   • If there are any missing dependencies the script will exit and display instructions. Once the dependency is satisfied, you can try again.

6. On completion you will see the OpenCRVS logo

7. Open the url http://localhost:3020/

8. You have successfully installed OpenCRVS! 🎉

9. Proceed to login using the details below

10. To stop OpenCRVS running in the installer, type Ctrl+c, then exit in each tmux terminal window

Log into OpenCRVS

Open the url http://localhost:3020/

Use one of the following authentication details for your user of choice. To learn about these user roles and to perform civil registration tasks, read our documentation

Field Agent

Username: kalusha.bwalya / Password: test / SMS code: 000000

Registration Agent

Username: felix.katongo / Password: test / SMS code: 000000

Registrar

Username: kennedy.mweene / Password: test / SMS code: 000000

Local System Admin

Username: emmanuel.mayuka / Password: test / SMS code: 000000

National System Admin

Username: jonathan.campbell / Password: test / SMS code: 000000

Starting and stopping OpenCRVS

After you have installed OpenCRVS. The setup script will have installed the opencrvs-farajaland country configuration in a directory alongside opencrvs-core. The country configuration is a separate server that must be started and stopped alongside opencrvs-core.

To start and stop opencrvs-core and the country configuration server, use the following commands.

Starting

1. Run cd opencrvs-core

2. Run pwd to output the path. (You have to pass the absolute path to opencrvs-core as a parameter when starting the country configuration )

3. Copy the path

4. Run yarn dev to start opencrvs-core

   If you did not previously run our setup command, Docker will have to download Mongo DB, ElasticSearch, OpenHIM and Hearth docker images. These are large files. Then docker will build them and you will see Mongo errors output for a long time until Mongo is running.

   If you did run our setup command, OpenCRVS will start much faster.

   Wait for the OpenCRVS client app to build completely (output will stop and you will see the message: @opencrvs/client: Compiled with warnings. Along with TypeScript/Node dependency warnings... ), then OpenCRVS Core will be available.

5. Open a new terminal window

6. Run cd ../opencrvs-farajaland

7. Run yarn dev <!-- paste in the absolute path to your opencrvs-core directory here --> to start the country configuration server

Stopping

1. Press Ctrl+c in the opencrvs-core terminal
2. Press Ctrl+c in the opencrvs-farajaland terminal

Other servers

When OpenCRVS is running, you can browse to other interesting servers such as:

React Storybook

Our UI component styleguide, available here: http://localhost:6060/

This is a work in progress

OpenHIM

OpenHIM is designed to ease interoperability between OpenCRVS and external systems such as Health & National ID. It provides external access to the system via secure APIs. OpenHIM channels and governs internal transactions, routing, orchestrating and translating requests into FHIR between services and the database layer.

1. Visit http://localhost:8888/#!/login

2. Login. username: [email protected] / Password: password

   When logging into OpenCRVS core locally, OpenHIM will display an error " ..if you are using a self-signed certificate, you may first need to instruct your browser to accept it.

   You can do so by accessing the following link." Click the link, and you will see the Chrome: Your connection is not private" error.

   This is nothing to worry about as when deploying OpenCRVS core to a server, our Traefik service provisions a LetsEncrypt SSL cert across the entire stack. Click "Advanced" & "Proceed to localhost (unsafe)". You will see output like this {"master":655.1310464,"now":1642447245037}.

   You can now go back to this OpenHIM link and login again freely: http://localhost:8888/#!/login

Configuring OpenCRVS

A companion example country configuration for Farajaland is checked out for you automatically using our setup script above. This country configuration server runs alongside opencrvs-core and serves languages, form configuration, logo files, adminisrative structure (jurisdictions and offices) etc. To see the code, learn more and fork for your requirements, visit the repo. opencrvs-farajaland.

What are the key OpenSource dependencies of OpenCRVS?

The following dependencies are automatically provisioned alongside the OpenCRVS Core in docker containers.

Hearth MongoDB Database layer

In order to support configuration for limitless country scale, OpenCRVS was designed for NoSQL, built on MongoDB, and aligned to a globally recognised healthcare standard.

Massively scalable and extensible, Hearth is an OpenSource NoSQL database server built by the OpenCRVS founding member Jembi Health Systems, using interoperable Health Level 7 FHIR v4 (ANSI Accredited, Fast Healthcare Interoperability Resources) as standard.

We innovatively extended FHIR to support the civil registration context. Our civil registration FHIR standard can be contributed to in this repository at Jembi.

ElasticSearch

De-duplication management to ensure data integrity is essential to any respectable civil registration system. A fast search engine lowers operational costs and improves the user experience for frontline staff.

OpenCRVS uses ElasticSearch, an industry standard, NoSQL document orientated, real-time de-duplication & search engine. Lightning fast, intelligent civil registration record returns are possible, even with imprecise, “fuzzy” search parameters.

InfluxData

Hyper efficient and optimised, Influx is a time series database for big data insights. Millisecond level query times facilitate civil registration statistical queries over months of data, disaggregated by gender, location and configurable operational and statistical parameters.

OpenHIM enterprise service bus, interoperability Layer

The OpenHIM (Health Information Mediator) is a NodeJS enterprise service bus designed to ease interoperability between OpenCRVS and external systems such as Health & National ID. It provides external access to the system via secure APIs. OpenHIM channels and governs internal transactions, routing, orchestrating and translating requests into FHIR between services and the database layer.

What is inside the OpenCRVS packages?

The core of OpenCRVS is a monorepo organised using Lerna. Each package reorts unit test coverage in Jest. Following the microservice, 1 service per container model, every package is independently scalable in a single docker container.

OpenCRVS microservice business layer packages

The OpenCRVS’ back end microservice architecture enables continuous evolution of its business requirements.

The microservices are written in TypeScript (a strictly typed superset of JavaScript that compiles to JavaScript) and NodeJS using the fully documented HapiJS framework.

Each microservice in OpenCRVS has no knowledge of other services or business requirements in the application, and each exposes it’s capabilities via JWT secured APIs.

Microservices:

• auth - the authentication microservice for OpenCRVS, JWT token generation and management in Redis.

⋅⋅⋅Our client applications are protected by SMS 2-Factor Authentication. Our apps and microservices utilise OAuth best practices for JWT tokens.

• commons - a shared library package that all microservices use in order to validate JWTs

• config - an application configuration microservice to serve country configuration settings in the upcoming Beta release scheduled for June 2022

• gateway - the GraphQL and Apollo API gateway for the OpenCRVS client.

Using GraphQL allows OpenCRVS to perform much faster and more responsively in remote areas by drastically reducing the number of HTTP requests that are required to render a view in the presentation layer.⋅⋅

The OpenCRVS GraphQL Gateway is a JWT protected Apollo server that requests and resolves FHIR resources from Hearth via OpenHIM into GraphQL, for easy consumption in the client applications.

• metrics - the civil registration metrics and analytics microservice using the Influx time series database.

• notification - the microservice that manages SMS communications from OpenCRVS, including content management and SMS supplier details.

• search - the search microservice for OpenCRVS using ElasticSearch

• user-mgnt - the user management microservice for the OpenCRVS client. User permissions and roles can be centrally managed, supporting IT organisations that conform to ISO27001 certification.

• workflow - the OpenCRVS business process orchestration microservice, mediating civil registration vital event status and audit updates.

OpenCRVS client application packages

• login - the login UI client built in React.

• client - the OpenCRVS UI client for civil registration built in React.

Client npm dependencies and enablers include:

• Easy build configuration with create-react-app, craco, typrescript-eslint

• Multi-lingual content management support using react-intl

• ES6 JS component styling using styled-components

• Fully configurable, high performance form management using formik

• Pure JavaScript, client side, offline PDF certificate generation using pdfmake

• Read-only application state management using redux

• Unit tests coverage with Jest & Enzyme UI component tests.

Using an Android progressive web application for our client app means that we can take advantage of offline functionality and native mobile features using Workbox, without the TCO overhead of maintaining multiple web and mobile codebases and respective App/Play Store releases.

In remote areas, registrars can save a configurable number of registrations offline on their mobile phone using IndexedDB.

OpenCRVS component library package

components - a UI component library package for the clients using React Styleguidist.

OpenCRVS performance testing packages

• integration - performance tests for OpenCRVS using the K6 framework.

What automated testing support is there?

Besides the thorough Jest unit testing coverage on opencrvs-core, we supply e2e UI test scripts using Cypress.

Because the OpenCRVS UI is completely configurable to your country, the end-to-end testing scripts are located in the example country configuration server for Farajaland.

Become part of the OpenCRVS Community

We want to see OpenCRVS implemented across the world. We can’t do this alone. Through the OpenCRVS Community, we are uniting experts in civil registration and other interested parties.

Visit our website

Join our Gitter community

Contributing

You may view/add issues here: https://github.com/opencrvs/opencrvs-core/issues

To contribute code, please review the CONTRIBUTING.md file https://github.com/opencrvs/opencrvs-core/blob/master/CONTRIBUTING.md, fork the repository and submit a pull request. The authors will review the code and merge it in if all is well.

By contributing to the OpenCRVS code, you are conforming to the terms of the license below.

How to tag an OpenCRVS release?

So you have contributed to core and want to make a new release as an OpenCRVS core repo admin?

1. Update all packages with the new version number according to semver. All packages will have the same version for simplicity as they are all designed to be used together. Update all dependencies to point to the newly created versions. E.g. client depend on components, so update the dependency: Do a find and replace for 1.0.0-alpha.2 and replace with 1.0.0-alpha.3

2. Run yarn to ensure there are no version errors.

3. Run yarn test and ensure all passed.

4. Run git tag v<version_number> e.g. git tag v1.0.0-alpha.3.1

5. Run git push origin v<version_number>

6. Create a new release on Github using the tag you just pushed and including any release notes.

7. Dockerhub should automatically build the images when a new release tag is created in Git. Howver Dockerhub can sometimes timeout and you may need to compose and push the release tagged images locally. To do that, run yarn compose:push:release

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

OpenCRVS is also distributed under the terms of the Civil Registration & Healthcare Disclaimer located at http://opencrvs.org/license.

Copyright (C) Plan International Inc, Plan International Australia, Jembi Health Systems NPC and Vital Strategies Inc.