• The setup steps and documentation below will have references to code-base and configurations from Bahmni-HWC Github repositories. You will see metadata and configurations that are configured for a pilot deployment at Karnataka State in India. As part of this initiative, we tried integrating Avni for offline use cases which will allow community health workers to capture data offline and sync it to Bahmni. Read more about it here (Bahmni Outreach App for Community Healthcare (Offline ready) ).

• This document will guide you on setting up a comprehensive integrated solution with Bahmni, Avni (named as Bahmni Outreach) with configuration and metadata related to Government of Karnataka Pilot. You will still be able to modify and explore most of the configuration but some would require code change. For more details on the refactoring to be done to make the integration service generic, refer here.

• More about Avni can be read from here: https://avniproject.org/features

Prerequisites for Setting Up Avni Services

1. Ensure that Docker and Docker Compose are installed on your system, and it is recommended to have the latest versions:
   a. Docker: Update to the latest version.
   b. Docker Compose: Ensure a minimum version of 2.10.x.

2. Clone the Bahmni-HWC/bahmni-india-package repository into your local environment. This contains the docker compose file with configurations for Bahmni EMR components, Bahmni Outreach (Avni) and ABDM components (India specific):

   git clone https://github.com/Bahmni-HWC/bahmni-india-package.git

3. Update /etc/hosts File:
   a. Find the local IP address of your machine using the ifconfig command. Look for a line resembling inet 192.168.1.101 netmask 0xffffff00 broadcast 192.168.1.255 and copy the inet IP address.
   b. Open the /etc/hosts file in an editor using the command:

   sudo nano /etc/hosts

   c. Add the following entry to the end of the file, replacing Machine_IP with the local network IP address of the machine:
   {Machine_IP} minio.avni.local

Setting up Avni services

Setting up Avni Services on your LAN with IP Address based Configuration:

This setup will be ideal for trying out Bahmni Outreach or for setting up a development environment.

1. Find the local IP address of your machine using the ifconfig command. Locate the inet entry in the command output, such as inet 192.168.1.101 netmask 0xffffff00 broadcast 192.168.1.255. Copy the IP address.

2. Update the .env file with the machine's IP address for the HOSTNAME variable.

3. Start Avni and Keycloak by running the following command:

   docker compose --profile keycloak --profile avni up -d

4. Keycloak will be accessible at http://<<machine_ip>>:8083/keycloak. Use the default login credentials: keycloakadmin/keycloak@dmin.

5. Wait for Avni to boot up. Access Avni at http://localhost:8021 or http://<<machine_ip>>:8021.

6. Log in to Avni superadmin using:

   Username: admin
Password: Admin123

7. Additionally, from the database backup, a default organization named Bahmni will be created with metadata. Use the following credentials to log in:
   Username: admin@bahmni
Password: Admin123
   These credentials can also be used to log in from the mobile app as well.

Troubleshooting

Dynamic IP Address:

1. If your local IP address changes, update the HOSTNAME variable in the .env file.

2. Update Keycloak and Avni services:

3. Additionally, update the IP in /etc/hosts for minio.avni.local.

Setting up Avni on a remote server with SSL certificates and DNS

The following steps to be followed when implementing Bahmni Outreach on a production setup / on a remote server like EC2 instances.

In-order for Avni to work on a remote setup, you would need to register four subdomains which will allow you to access different services of Avni. All these four sub-domains can be mapped to the same public IP address of the server in your DNS provider. Routing to individual services based on domain name is handled with VirtualHosts in the proxy configuration file.

Once you have mapped the DNS names in your DNS provider, update the domain names in avni-proxy.conf file under respective VirtualHosts server name. Also update the MINIO_URL variable in .env file with https://minio.<your_domain> and KEYCLOAK_BASE_URL with https://<bahmni>.<your_domain>/keycloak.

Next step is to generate an SSL certificate. The SSL certificate should either be a wildcard certificate for your root domain *.<your_domain> or should be a SAN certificate containing the above four sub domains.

When you have got the SSL certificate, rename the fullchain cert file as cert.pem and private key file as key.pem and add it to a directory. Update the directory path in the CERTIFICATE_PATH in the .env file. Now you can start the containers by running

Setting up MinIO

1. Start MinIO:

• Launch MinIO by executing the following command:

2. Update /etc/hosts File (needed only on local setup):

• Open the /etc/hosts file in an editor:
  sudo nano /etc/hosts

• Add the following entry at the end, replacing Machine_IP with the local network IP address:{Machine_IP} minio.avni.local

3. Access MinIO Console:

• Open a browser and navigate to http://minio.avni.local:9000 or minioconsole.<your_domain>.

• Log in using the default credentials: root/root@123.

4. Create a Bucket:

5. Create Access Key:

6. Update Avni Containers:
   Update the AVNI_MINIO_ACCESS_KEY and the AVNI_MINIO_SECRET_ACCESS_KEY variables in the .env file. Recreate docker containers by running
   docker compose --profile avni --profile minio up -d

7. Verify Image Uploads:

Follow these steps to set up MinIO for file uploads and metadata operations within Avni. Adjust configurations as needed based on your specific environment.

Downloading and Setting up Bahmni Outreach APK

Open the latest workflow with the job name avni-apk in avni-client repo and download APK from artifacts section on the GitHub Actions page:

https://github.com/Bahmni-HWC/avni-client/actions

Setting up Avni Integration Service

Start avni Integration service by running the following command:

Creating a New User in Avni and Creating a Mapping in Integration Service

Creating a New User in Avni

1. Login to Avni Web Console at https://localhost:8021 with admin@bahmni:

   1. Navigate to Admin -> Users.

2. Create New User:

   1. Click on "Create" to add a new user

   2. Fill in the required details for the new user

   3. Click "Save" to create the user.

3. After creating the user, use the Reset Password option to set the initial password for the user.

Assigning Identifiers to Users

1. Login to Avni Web Console:

   1. Navigate to Admin -> Identifier User Assignment.

2. Create Identifier Assignment:

   1. Click on "Create."

3. Select the user for whom you want to assign an identifier.

4. Choose the Identifier Source.

5. Set Identifier start and end values.

   1. Example: Start → KA101001 End → KA102000

6. Click "Save" to assign identifiers to the user.

Creating a Provider and Adding a Mapping in Integration Service

Refer below link to create a user and provider in OpenMRS:

https://bahmni.atlassian.net/wiki/spaces/BAH/pages/34013682/Configure+Users

Creating New Locations and Catchments in Avni

Creating New Locations

Login to Avni Web Console:

• Navigate to Admin -> Locations.

Create a New Location:

• Click on "Create."

• Enter the name of the new location.

• Choose the type (City/Village, Sub District, District, State).

• If the location is part of another location, select the larger location from the "Part of (location)" dropdown.

• Click "Save" to create the new location.

Creating New Catchments

Login to Avni Web Console:

• Navigate to Admin -> Catchments.

Create a New Catchment:

• Click on "Create."

• Enter the name of the catchment.

• Choose a location from the dropdown.

• Click "Save" to create the new catchment.
  Note: Ensure that the new locations and catchments are appropriately configured to meet the requirements of your Avni setup.

Security guidelines

1. To enhance the security of your Avni Keycloak instance, follow these steps to change the default AVNI Keycloak Client Secret:

• Access the Keycloak Admin Console.

• Navigate to Clients > Client Details > admin-api > Client Secret.

• Click "Regenerate" to generate a new secret.

• Update the .env file with the new secret.

This ensures a more secure setup by using a custom client secret in your Keycloak instance.

2. To ensure proper integration between Avni and MinIO, it is essential to update the AVNI_MINIO_ACCESS_KEY and AVNI_MINIO_SECRET_ACCESS_KEY variables in the .env file every time MinIO is started fresh.

3. Update the default credentials for the Avni Integration user (integration@bahmni), ensure that you also update the corresponding environment variables AVNI_INTEGRATION_USER and AVNI_INTEGRATION_PASSWORD in the env file.

4. Update the Keycloak Admin user by logging into Keycloak

5. Update the default passwords of admin@bahmni user from Avni Admin Console → Admin → Users.

Creating a new form and mapping to Bahmni from integration service

1. Navigate to the Avni Web Console.

2. Go to the "Home" tab.

3. Select "App Designer" from the menu.

4. Under "Forms," click on "New Form."

5. Select the desired form type from dropdown options:
   a. Subject registration
   b. Subject enrolment eligibility
   c. Manual enrolment eligibility
   d. Program enrolment
   e. Program exit
   f. Program encounter
   g. Program encounter cancellation
   h. Encounter
   i. Individual Encounter Cancellation
   j. Check list item
   k. Location
   l. Task

6. Provide a name for the form in the designated field.

7. Click the "ADD" button to create the new form.

Following these steps will help you create a new form in the Avni Web Console with the selected form type and the specified name.

Bahmni Outreach Docker Image Repositories

List of features available in Bahmni Outreach out of the box

1. Patient registration

   1. Demographic data

   2. Additional Identifiers

      1. ABHA Number

      2. ABHA Address

      3. RCH ID

      4. Nikshay ID

   3. Patient Attributes

      1. Phone Number

      2. Father / Mother name

2. List of forms available to capture data and syncs to Bahmni:

   1. Vitals Form

   2. History and Examination Form

   3. Referral Form

   4. Dispense Medication Form

   5. Rapid Lab Tests (Not synced to Bahmni)

3. List of items synced from Bahmni to Outreach App:

   1. Vitals

   2. Prescriptions (synced as bulleted items)

   3. Diagnosis (synced as bulleted items)

4. Camp Activity (Not synced to Bahmni):
   This is a separate subject type in Avni which can be used to capture information about any outreach activities / events conducted by the CHW’s.

5. ABHA Module (India Specific):

   1. This is a separate android library written in Kotlin to support creation and linking of patient’s unique health id.

   2. More about Bahmni Integration with India’s health mission can be read here.

   3. The module is launched from the Bahmni Outreach App where the module talks with Bahmni’s HIP Service over rest APIs and returns back patient data to Outreach app.

   4. Code repository:

6. eSanjeevani Integration (India Specific):

   1. eSanjeevani is India’s National Telemedicine service. eSanjeevani facilitates quick and easy access to doctors and medical specialists from your smartphones.

   2. Integration with eSanjeevani is done over REST API where the patients registered in Bahmni EMR system are registered on the eSanjeevani portal upon initiating consultation thereby reducing the re-entry of data into different portal by the community health workers.

   3. Code Repository for eSanjeevani Micro Service: