OpenCRVS
OpenCRVS Docs 1.1
Search…
⌃K
Links

3.3.2 Install dependencies

Ansible is required to be installed on your local development machine in order run the server setup commands. Installation instructions are here. 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 and the 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 will need an account on Dockerhub to build and push your country configuration image. Dockerhub is a free containerisation repository.
  1. 1.
    Create an account on Dockerhub as Ansible and Github Actions will require your Dockerhub username and password in order to login.
  2. 2.
    Referring to the opencrvs-core repository, duplicate the example-X.ini inventory_file of choice where X is relative to the number of servers. These can be found in the infrastructure/server-setup 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: example-1.ini file to run with the Ansible playbook_file: playbook-1.yml explained below. Note: Only 1 server is not recommended for production deployments If you are deploying to a standard production deployment of 3 servers, you need to make a copy of the inventory_file: example-3.ini file to run with the Ansible playbook_file: playbook-3.yml explained below. If you are deploying to 5 servers, you need to make a copy of the inventory_file: example-5.ini file to run with the Ansible playbook_file: playbook-5.yml explained below.
  3. 3.
    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=farajaland-staging
As of v1.1.0 a country configuration playbook.yml is loaded by all of the playbooks above in order to configure secret storage for the passwords explained next.
4. Using a strong password generator, such as 1Password you should create and safely store the following parameters:
mongodb_admin_username
mongodb_admin_password
encrypt_passphrase
elasticsearch_superuser_password
Make sure that you record these for future use as you will need the details in the deployment Github Actions.
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
country_config_path (The local path to your country configuration directory)
PRODUCTION NOTE: In production, you will need to provision a Hardware Security Module and amend the country configuration playbook.yml, decrypt.sh, emergency-backup-metadata.sh and emergency-restore-metadata.sh scripts at the linked locations in order to change the approach to storing and accessing the disk_encryption_key and MongoDB and Elasticsearch passwords. Our supplied approach is not production ready. Secure secret storage is currently outside the scope of OpenCRVS.
In the December OpenCRVS release v.1.2.0 we intend to show an example of how an HSM could be configured. In the meantime, MOSIP's documentation on the requirements of a Hardware Security Module is useful reading.
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
Ansible playbooks are run like this from your local machine:
If you are on the root directory of the opencrvs-core repository, navigate to the server-setup folder:
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> \
country_config_path=<local path to your country config folder> \
encrypt_data=True"
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> \
country_config_path=<local path to your country config folder> \
encrypt_data=True \
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>"
Once this command is finished the servers are prepared for an OpenCRVS deployment. You can read more about the external backups in the Emergency Backup & Restore section