Purpose

The guide covers everything developers need to know to set up and run DIVOC on their local machines.

What will it cover?

• API documentation

• Setting up DIVOC development environment

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

This section includes the following:

1. Admin API (swagger)

2. Vaccination API (swagger)

3. Certificate Access API (swagger)

4. Registration API (swagger)

All content on this page by eGov Foundation is licensed under a Creative Commons Attribution 4.0 International License.

This will cover the following:

• Running DIVOC on a local machine

• DIVOC walkthrough

Running DIVOC on a local machine

Steps

Step 1: Install prerequisites and dependencies

• Update package list - sudo apt-get update.

• Install docker - sudo apt install docker.io.

• Install docker-compose - sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose.

• Install git - sudo apt install git.

• For additional details on Docker, you can find the instructions here.

• You can find the basic Docker Compose commands below:

- Starting services docker-compose up.

- Restarting services docker-compose restart.

- Checking the status of services docker-compose ps.

- Monitoring service logs docker-compose logs.

Step 2: Install DIVOC

• Clone DIVOC repository onto your local machine - git clone https://github.com/egovernments/DIVOC.

• Navigate to DIVOC directory - cd DIVOC.

• Configure DIVOC: Configurations are provided as environment variables and a default set of configurations is provided in the ‘.env.example’ file. Make a copy of this file named ‘.env’ that docker will pick up. Edit these configurations as per your need.

   'cp .env.example .env'

Step 3: Start all services in the detached mode.

docker-compose up -d

• Verify the state of containers. All containers should be up.

• Some services might fail to start because the dependent service may not be ready yet. Restarting the failed service should start it successfully in this case.

• On Mac/Windows, services may crash with exit code:137, if sufficient memory is not set for docker. This can be changed in the Docker desktop preferences, resources tab, as shown here.

Step 4: To build docker images locally after making changes, run following commands

make docker
make docker docker-compose up -d

Step 5: Explore DIVOC

• The following are the routes to access local apps. The remaining routes can be found in nginx/nginx.conf.

DIVOC walkthrough

In this section, we will go through the steps involved in a typical flow, starting from setting up facilities to generating a certificate after vaccination.

Set up Keycloack

• Login to keycloak console (localhost/auth/admin) as admin (password : admin)

• Hover on Master on the left top corner and click on Add realm.

• Click on the Select File button (import option).

• Select realm-export.json in the keycloak directory. path:DIVOC/keycloak.

• Click on create.

Set up CLIENT_SECRET for admin-api

• Login to the keycloak console (localhost/auth/admin) as admin (password:admin).

• Click on Clients in the configure section on the left pane and click on admin-api.

• Go to the credentials tab, click on Regenerate Secret and copy the new secret.

• Change the ADMIN_API_CLIENT_SECRET to the copied secret in docker-compose.yml.

• Rebuild and restart the services that use ADMIN_API_CLIENT_SECRET.

docker-compose up -d --build --no-deps <service1> <service2>...
 docker-compose restart nginx

“For example - sudo docker-compose up -d --build --no-deps certificate-processor portal-api certificate-api gateway.

DIVOC application configuration

DIVOC uses etcd as a configuration store for templates and other configurations. A default set of configurations is available in the default-configuration/etcd folder. The instructions to configure these are available here.

Create admin and controller users in Keycloak

• Login to the keycloak console (localhost/auth/admin) as admin (password : admin).

• Click on Users in the Manage section on the left panel and click on Add User.

• Give the username as 0000000000 and click on save.

• In the Attributes section, add a new key as mobile_number and value as 0000000000. Click on Add and save.

• Go to the Groups section, select system admin in the available groups and click on Join.

• Similarly, create another user with username and mobile_number as 0000000001 and join the controller group.

System admin activities

Login to the portal as system admin (Mobile Number : 0000000000, OTP : 1234).

Upload Facilities.csv:

• Click on the Facilities tab and click on Download Template .csv.

• Click on Upload CSV button and upload the downloaded csv.

• You should see the success message for a facility.

Create a vaccine:

• Click on the Vaccines tab. Fill in all the fields on the form, mark the status as Active and click on save.

• You should see the new vaccine on the right pane in the list of registered medicines/vaccines.

Create a vaccination program:

• Click on the Vaccine Program tab. Fill in all the fields on the form, mark the status as Active, and click on save.

• You should see the new vaccine program on the right pane in the list of registered vaccine programs.

Pre-enroll recipients:

• Click on the Pre-Enrollment tab and click on Downloaf Template .csv

• Click on Upload CSV and upload a CSV file containing all the fields given in the template.

• You should see the number of recipients successfully enrolled and errors if there are any.

Controller activities

Login to the portal as controller (Mobile Number: 0000000001, OTP: 1234).

Activate facilities for vaccination program:

• In the Facility Activation tab, select the vaccination program added in the previous step, select the type of facility as government and mark the status as Active.

• You should be able to see at least one facility in the search results.

• Click on the checkbox for the relevant facility (make note of facility code) and click on MAKE ACTIVE.

• The activated facility should disappear from the search results.

Facility admin activities

Get admin mobile number for the facility code (noted in the previous step), from the facilities.csv uploaded.

Login to Facility Admin portal (localhost/portal/facility_admin) using the mobile number and OTP: 1234.

Add facility_staff user:

• Click on the Role Setup tab and click on the add role icon.

• Create a role with type facility staff and mobile number 1111111111. Set the status as enabled and set the rate of 50 for the vaccination program.

Add Vaccinators:

• Click on Vaccinator Details tab and Click Add Vaccinator.

• Fill in all the details. Select the vaccination program previously created in the certification dropdown.

• Click on Add and click on Back.

• Click on the Make Active button to activate the vaccinator.

Bulk Certification:

• Certificates can also be issued in bulk by the facility admin by uploading a CSV file.

• Go to the Upload Vaccination details tab and click on the download CSV template button.

• Now upload a CSV file, containing all the fields in the template.

• The generated certificates can be viewed on the public app (localhost).

Facility staff activities

Login to the Facility app (localhost/facility_app) (Mobile Number: 1111111111, OTP: 1234).

Enrolling and certifying recipients:

• Click on enrol recipient, fill all the details and proceed.

• Click on Recipient Queue, to proceed for certification.

Certifying pre-enrolled recipients:

• Recipients pre-enrolled by facility admin can be certified by the facility staff.

• Go to the app home and click on Verify Recipient to proceed for vaccination.

Recipient activities

• In the public app (localhost), recipients can:

  • Download/ vaccination certificates

  • Verify certificates by scanning a QR code

  • Report any side effects/symptoms after vaccination

• For the above operations, you need the recipient mobile number (given during pre-enrollment/vaccination). Use OTP: 1234 for all logins.

Deployment note

Change the admin password of Keycloak console

• Go to the admin console, click on the Admin menu in the top right corner and select Manage account.

• Change the password in the password section on the right.