Install and Setup Bahmni Outreach Community App
BAHMNI OUTREACH COMMUNITY APP (AVNI)
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
TABLE OF CONTENTS
- 1 Prerequisites for Setting Up Avni Services
- 2 Setting up Avni services
- 3 Downloading and Setting up Bahmni Outreach APK
- 4 Setting up Avni Integration Service
- 5 Creating a New User in Avni and Creating a Mapping in Integration Service
- 6 Creating New Locations and Catchments in Avni
- 7 Security guidelines
- 8 Creating a new form and mapping to Bahmni from integration service
- 9 Bahmni Outreach Docker Image Repositories
- 10 List of features available in Bahmni Outreach out of the box
Prerequisites for Setting Up Avni Services
We recommend going through the official Avni documentation to get a basic understanding of different components of Avni and its domain model. Official Documentation Link: https://avni.readme.io/docs/getting-started . This diagram also gives the high level architecture of how different components of Avni and Bahmni talk to each other.
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.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
Update /etc/hosts File:
a. Find the local IP address of your machine using theifconfig
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.
Find the local IP address of your machine using the
ifconfig
command. Locate theinet
entry in the command output, such asinet 192.168.1.101 netmask 0xffffff00 broadcast 192.168.1.255
. Copy the IP address.Update the
.env
file with the machine's IP address for the HOSTNAME variable.Start Avni and Keycloak by running the following command:
docker compose --profile keycloak --profile avni up -d
Keycloak will be accessible at
http://<<machine_ip>>:8083/keycloak
. Use the default login credentials:keycloakadmin/keycloak@dmin
.Wait for Avni to boot up. Access Avni at http://localhost:8021 or
http://<<machine_ip>>:8021
.Log in to Avni superadmin using:
Username: admin
Password: Admin123
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:
If your local IP address changes, update the HOSTNAME variable in the
.env
file.Update Keycloak and Avni services:
Additionally, update the IP in
/etc/hosts
forminio.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.
Domain Format | Routes to |
---|---|
bahmni.<your_domain> | This is the root domain which will allow you to access Bahmni and Keycloak |
bahmni-offline.<your_domain> | Avni server API’s and Admin Console |
minio.<your_domain> | Allows MinIO S3 API communication |
minioconsole.<your_domain> | Allows access to MinIO Web UI |
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
docker compose up -d
Setting up MinIO
Start MinIO:
Launch MinIO by executing the following command:
docker compose --profile minio up -d
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
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
.
Create a Bucket:
From the MinIO console, create a bucket named avni
. If using a different name, update the AVNI_MINIO_BUCKET_NAME
variable in the .env
file.
Create Access Key:
Create an Access Key from the MinIO console. Copy the access key and secret access key.
Update Avni Containers:
Update theAVNI_MINIO_ACCESS_KEY
and theAVNI_MINIO_SECRET_ACCESS_KEY
variables in the .env file. Recreate docker containers by runningdocker compose --profile avni --profile minio up -d
Verify Image Uploads:
Once the containers are recreated, check the MinIO console. Images uploaded from forms in Avni should be visible in the avni bucket.
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
Login to Avni Web Console at https://localhost:8021 with admin@bahmni:
Navigate to Admin -> Users.
Create New User:
Click on "Create" to add a new user
Fill in the required details for the new user
Click "Save" to create the user.
After creating the user, use the Reset Password option to set the initial password for the user.
Assigning Identifiers to Users
Login to Avni Web Console:
Navigate to Admin -> Identifier User Assignment.
Create Identifier Assignment:
Click on "Create."
Select the user for whom you want to assign an identifier.
Choose the Identifier Source.
Set Identifier start and end values.
Example: Start → KA101001 End → KA102000
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
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.
To ensure proper integration between Avni and MinIO, it is essential to update the
AVNI_MINIO_ACCESS_KEY
andAVNI_MINIO_SECRET_ACCESS_KEY
variables in the.env
file every time MinIO is started fresh.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.Update the Keycloak Admin user by logging into Keycloak
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
Navigate to the Avni Web Console.
Go to the "Home" tab.
Select "App Designer" from the menu.
Under "Forms," click on "New Form."
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. TaskProvide a name for the form in the designated field.
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
| Docker Image | Description | Github Repository from where image is published |
---|---|---|---|
1 | Bahmni configuration for clinics/ small hospitals. Loaded with CIEL concepts. | ||
2 | This is the Administration Interface where you can configure and set up the Avni server. It can also be used for Data Imports, Exports, and Data-Entry. | ||
3 | A centralized place to keep data persistent and to enable sharing of data between different devices. | ||
4 | To automate setup of avni-server for on-premise environment | ||
5 | Image which syncs data between Bahmni to Bahmni outreach vice versa. | ||
6 | This is db back-up for avni integration service containing the required mappings for Concepts and forms | ||
7 | This is db back-up for avni server which comes with a organisation created, containing admin user, integration user. |
List of features available in Bahmni Outreach out of the box
Patient registration
Demographic data
Additional Identifiers
ABHA Number
ABHA Address
RCH ID
Nikshay ID
Patient Attributes
Phone Number
Father / Mother name
List of forms available to capture data and syncs to Bahmni:
Vitals Form
History and Examination Form
Referral Form
Dispense Medication Form
Rapid Lab Tests (Not synced to Bahmni)
List of items synced from Bahmni to Outreach App:
Vitals
Prescriptions (synced as bulleted items)
Diagnosis (synced as bulleted items)
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.ABHA Module (India Specific):
This is a separate android library written in Kotlin to support creation and linking of patient’s unique health id.
More about Bahmni Integration with India’s health mission can be read here.
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.
Code repository:
eSanjeevani Integration (India Specific):
eSanjeevani is India’s National Telemedicine service. eSanjeevani facilitates quick and easy access to doctors and medical specialists from your smartphones.
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.
Code Repository for eSanjeevani Micro Service:
The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)