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
- Starting and stopping OpenCRVS
- Other servers
- Configuring OpenCRVS
- What are the key OpenSource dependencies of OpenCRVS?
- What is inside the OpenCRVS packages?
- Become part of the OpenCRVS Community
- Contributing
- License
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.
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.
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 tmuxto install. On Mac, you can install tmux using Homebrew or MacPorts.
-
Check you have installed all the dependencies. See above.
-
Run
git clone[https://github.com/opencrvs/opencrvs-core.git](https://github.com/opencrvs/opencrvs-core.git) -
Run
git checkout master -
Run
cd opencrvs-core -
Run
bash setup.sh(takes 10-15 minutes)This installer script will:
- Tests your dependencies
- Checks that required ports are available. NOTE: Latest Macbooks run AirPlay on port 5000. Some Mac users need to disable AirPlay when running OpenCRVS.
- Download and install all Docker images
- Check out the example OpenCRVS country configuration
- Runs all OpenCRVS Core microservices
- Run the OpenCRVS Zambia country configuration and populate local databases with Zambia country configuration reference data
- If there are any missing dependencies the script will exit and display instructions. Once the dependency is satisfied, you can try again.
-
On completion you will see the OpenCRVS logo
-
Open the url
http://localhost:3020/ -
You have successfully installed OpenCRVS! 🎉
-
Proceed to login using the details below
-
To stop OpenCRVS running in the installer, type Ctrl+c, then exit in each tmux terminal window
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
Username: kalusha.bwalya / Password: test / SMS code: 000000
Username: felix.katongo / Password: test / SMS code: 000000
Username: kennedy.mweene / Password: test / SMS code: 000000
Username: emmanuel.mayuka / Password: test / SMS code: 000000
Username: jonathan.campbell / Password: test / SMS code: 000000
After you have installed OpenCRVS. The setup script will have installed the opencrvs-zambia 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.
-
Run
cd opencrvs-core -
Run
pwdto output the path. (You have to pass the absolute path to opencrvs-core as a parameter when starting the country configuration ) -
Copy the path
-
Run
yarn devto start opencrvs-coreIf 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.
-
Open a new terminal window
-
Run
cd ../opencrvs-zambia -
Run
yarn dev <!-- paste in the absolute path to your opencrvs-core directory here -->to start the country configuration server
- Press Ctrl+c in the opencrvs-core terminal
- Press Ctrl+c in the opencrvs-zambia terminal
When OpenCRVS is running, you can browse to other interesting servers such as:
Our UI component styleguide, available here: http://localhost:6060/
This is a work in progress
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.
-
Login. username: root@openhim.org / 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
A companion example country configuration for Zambia 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-zambia.
The following dependencies are automatically provisioned alongside the OpenCRVS Core in docker containers.
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.
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.
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.
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.
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.
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:
⋅⋅⋅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 microservoce pa
-
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.
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
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.
components - a UI component library package for the clients using React Styleguidist.
- integration - performance tests for OpenCRVS using the K6 framework.
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 Zambia.
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.
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.
So you have contributed to core and want to make a new release as an OpenCRVS core repo admin?
-
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.
clientdepend oncomponents, so update the dependency: Do a find and replace for1.0.0-alpha.2and replace with1.0.0-alpha.3 -
Run
yarnto ensure there are no version errors. -
Run
yarn testand ensure all passed. -
Run
git tag v<version_number>e.g.git tag v1.0.0-alpha.3.0 -
Run
git push origin v<version_number> -
Create a new release on Github using the tag you just pushed and including any release notes.
-
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
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.