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
  1. Setup
  2. 3. Installation
  3. 3.3 Set-up a server-hosted environment

3.3.2 Provision environment

Previous3.3.1 Provision your server nodes with SSH accessNext3.3.3 Provision a comms gateway

Last updated 1 year ago

In OpenCRVS v1.3.1 hotfix scheduled for November 6th 2023, we will be releaseing a Github Action to automate this process. :-)

is required to be installed on your local development machine in order to provision the server with required software. Installation instructions are . Ensure that you have ssh access using the root user to all the servers that you are trying to configure.

Ansible is an IT automation tool that you install locally and run from your local computer. It uses SSH to connect to your servers automatically and installs all the supporting software and configures Ubuntu for you to be able to deploy OpenCRVS. The Ansible script we provide will install all the dependencies onto your server nodes, configure a secure firewall, open required ports and provision the optional automated backup of OpenCRVS for use in production. You may need to customise our Ansible playbooks depending on your hosting provider and the access you have.

You will need a docker container registry account on to build and push your country configuration image, in order to use our Ansible script. This is because the server needs access to your containrer registry account to pull images from it. is a free containerisation repository. You can customise our Ansible script if you wish to use a different registry.

In OpenCRVS v1.3, all server setup configuration and deployment files exist in the country configuration repository - e.g. opencrvs-countryconfig. This allows you to completely customise them for your needs without needing to fork opencrvs-core

  1. Create an account on as Ansible and Github Actions will require your Dockerhub username and password in order to login.\

  2. Referring to the country configuration repository e.g. opencrvs-countryconfig, duplicate the example-X.ini inventory_file of choice where X is relative to the number of servers. These can be found in the directory, depending upon whether or not you are deploying to 1, 3 or 5 servers. For example: If you are only deploying to 1 server, you need to make a copy of the inventory_file: file to run with the Ansible playbook_file: explained below. If you are deploying to a standard production deployment of 3 servers, you need to make a copy of the inventory_file: file to run with the Ansible playbook_file: explained below. If you are deploying to 5 servers, you need to make a copy of the inventory_file: file to run with the Ansible playbook_file: explained below.

Deploying to only 1 server is not recommended and is CONSIDERABLY RISKY for a production installation. YOU COULD LOSE CITIZEN DATA IF THE SERVER CRASHES. Docker Swarm's power is that it can load balance between servers in a cluster. If one of the servers goes down, the others will still be operational.

You will be required to uncomment some lines to enter the IP addresses and hostnames, e.g.:\

;manager1 ansible_host="ENTER YOUR MANAGER HOST IP"

becomes:

manager1 ansible_host="159.223.11.243"

... and:

;data1_hostname=ENTER_HOSTNAME_1

becomes:

data1_hostname=<your server hostname>

4. Using a strong password generator, such as you should create and safely store the following parameters.:

mongodb_admin_username

mongodb_admin_password

elasticsearch_superuser_password

5. You are now ready to call the Ansible command passing these required parameters and additionally some optional parameters.

Required parameters:

dockerhub_username

dockerhub_password

mongodb_admin_username

mongodb_admin_password

elasticsearch_superuser_password

disk_encryption_key

encrypted_disk_size

Depending on the size of your server, encrypted_disk_size should be equal to about 80% of your available disk. E.G. for a 320GB disk, encrypt 256GB to store OpenCRVS data. You need to leave enough unencrypted space for your operating system and software. The encrypted_disk_size prop for 256GB is: 256g

Optional parameters:

For the optional automated daily external data backup to another server, these parameters must be prepared:

external_backup_server_ip

external_backup_server_user

external_backup_server_ssh_port

external_backup_server_remote_directory

You must ensure that you are in your local computer and that both your local directories opencrvs-core and opencrvs-<your country> are on the same release version v* or master branch before running Ansible. Ansible is run from your local machine and it connects to your server using SSH and automatically runs commands on it.

Ansible playbooks are run like this from your local machine:

cd infrastructure/server-setup

Now you can run the playbook like this, substituting the parameters as required:

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> \
encrypted_disk_size=<your available disk size for encryption, e.g. 256g>"

Or with all the possible optional props:

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> \
encrypted_disk_size=<your available disk size for encryption, e.g. 256g> \
external_backup_server_ip=<your_external_backup_server_ip> \
external_backup_server_user=<your_external_backup_server_user> \
external_backup_server_ssh_port=<your_external_backup_server_ssh_port> \
manager_production_server_ip=<your_manager_production_server_ip> \
external_backup_server_remote_directory=<your_external_backup_server_remote_directory>"

We suggest that your passwords are unguessable alphanumeric version 1 or 4 . If you use special characters in the passwords, they will need to be escaped.

The passwords and secret keys that you make in this section are critically important to be saved and stored securely. They are the master keys to access your citizen data! Consider Password Management Policies!! Tools such as can help you here. You can customise our playbook to store the keys in a .

disk_encryption_key (The Disk encryption secret, encrypting your citizen data at rest.)

You must store these keys safely for future use, as you will need the details in the process.

PRODUCTION NOTE: In production, we advise that you provision a and amend the country configuration , , and scripts at the linked locations in order to change the approach to storing and accessing the disk_encryption_key and MongoDB and Elasticsearch passwords. Secure secret storage is currently outside the scope of OpenCRVS.

MOSIP's documentation on the requirements of a is useful reading.

If you are on the root directory of the country configuration repository - e.g. opencrvs-countryconfig, navigate to the folder:

Once this command is finished the servers are prepared for an OpenCRVS deployment. You can read more about how the external backups work in the section

Ansible
here
Dockerhub
Dockerhub
Dockerhub
infrastructure/server-setup
example-1.ini
playbook-1.yml
example-3.ini
playbook-3.yml
example-5.ini
playbook-5.yml
1Password
RFC 4122
UUIDs
ISO270001
1Password
hardware security module
LUKS
deploy
Hardware Security Module
playbook.yml
decrypt.sh
emergency-backup-metadata.sh
emergency-restore-metadata.sh
Hardware Security Module
server-setup
Automated & manual backup...