Bahmni AI Module - Complete Installation & Configuration Guide

This guide provides step-by-step instructions for installing and running the Bahmni AI Assistant module integrated with Bahmni EMR using the Groq LLM API.

Table of Contents

1. Prerequisites
2. Getting a Groq API Key
3. Installation
4. Configuration
5. Starting Bahmni
6. Verifying the Installation
7. Accessing the AI Assistant
8. Troubleshooting
9. Updating & Maintaining
10. Uninstalling

---

Prerequisites

Before starting, verify you have:

Required Software

• Docker - Container runtime (version 20.10+)
• Docker Compose - Container orchestration (version 1.29+)

To verify installation:

docker --version      # Should show version >= 20.10
docker-compose --version  # Should show version >= 1.29

Required Project Structure

Your project must have both directories at the same level:

your-project/
├── bahmni-docker/          # Bahmni Docker Compose setup
│   ├── bahmni-standard/    # Standard installation (or bahmni-lite)
│   │   ├── docker-compose.yml
│   │   ├── .env
│   │   └── run-bahmni.sh
│   └── ...
├── ai-module/              # AI Assistant module
│   ├── setup-ai-integration.sh
│   ├── install.sh
│   ├── verify-ai-integration.sh
│   ├── config/
│   ├── files/
│   └── ...

Active Groq API Key

You need a free Groq API key to use the AI Assistant. See Getting a Groq API Key below.

---

Getting a Groq API Key

The AI Assistant uses the Groq Cloud API for AI inference. Follow these steps to get a free key:

Step 1: Create a Groq Account

1. Visit https://console.groq.com
2. Click Sign Up (or Sign In if you have an account)
3. Complete the registration with your email
4. Verify your email address

Step 2: Generate an API Key

1. In the Groq console, navigate to API Keys (usually in sidebar menu)
2. Click Create New API Key
3. Give it a name like "Bahmni-AI" for easy identification
4. Click Generate or Create
5. Copy the key immediately - you won't be able to see it again

The key will look like:

gsk_aBcDeFgHiJkLmNoPqRsT123uVwXyZ456

Step 3: Keep It Safe

• Never commit this key to Git - it gives access to your Groq account
• Store it securely in your .env file only
• If you accidentally expose it, regenerate a new one in the Groq console

---

Installation

Follow these steps in order. Run all commands from your project root directory.

Step 1: Navigate to AI Module Directory

cd ai-module

Step 2: Run the Installation Script

For Bahmni Standard (recommended for full features):

./setup-ai-integration.sh install --bahmni-standard

For Bahmni Lite only:

./setup-ai-integration.sh install --bahmni-lite

For both Standard and Lite:

./setup-ai-integration.sh install --all

If your bahmni-docker directory is in a different location, specify it explicitly:

./setup-ai-integration.sh install --bahmni-standard --bahmni-docker-path /path/to/bahmni-docker

Step 3: Expected Output

The installation script should complete with success messages like:

✓ All required files found
✓ Bahmni Standard installation found at: /path/to/bahmni-docker/bahmni-standard
✓ Backed up Bahmni Standard/.env
✓ Merged AI configuration into Bahmni Standard/.env
✓ Normalized AI runtime defaults in Bahmni Standard/.env
✓ Created Bahmni Standard/docker-compose.override.yml
✓ Injected custom display control into Bahmni Standard
✓ Docker Compose configuration is valid for Bahmni Standard
✓ Post-install verification passed for Bahmni Standard

Step 4: What Was Installed

The installation script automatically:

• ✓ Creates docker-compose.override.yml with AI services
• ✓ Merges AI configuration into .env
• ✓ Sets up the UI extension for the AI Assistant button
• ✓ Configures Docker volumes and environment defaults
• ✓ Creates backups of original configurations
• ✓ Validates the Docker Compose configuration

Backups: Original configurations are backed up at:

ai-module/backups/backup_YYYYMMDD_HHMMSS/Bahmni Standard/

---

Configuration

Step 1: Add Your Groq API Key

Edit the .env file in your Bahmni Standard directory:

nano bahmni-docker/bahmni-standard/.env

Or use your preferred editor (VSCode, vim, etc.)

Find or add this line:

GROQ_API_KEY=gsk_your_actual_key_here

Replace gsk_your_actual_key_here with your actual key from Groq (step from above).

Example:

GROQ_API_KEY=gsk_aBcDeFgHiJkLmNoPqRsT123uVwXyZ456

Save the file (Ctrl+O, Enter, Ctrl+X in nano).

Step 2: Verify Critical Configuration

Check these important settings are present in .env:

# Must be present and enabled
COMPOSE_PROFILES=emr,ai
OPENMRS_SESSION_AUTH_ENABLED=true

# Recommended security settings
OPENMRS_ALLOW_INSECURE_TLS=false

# AI service configuration (auto-set by installer)
AI_FRONTEND_BASE_PATH=/openmrs/ai-assistant
AI_API_BASE_PATH=/openmrs/ai-api
AI_BACKEND_INTERNAL_URL=http://ai-backend:3001
GROQ_MODEL=llama-3.3-70b-versatile
EMR_BASE_URL=http://openmrs:8080/openmrs/ws/rest/v1

All of these should be automatically set. If any are missing, add them manually.

Step 3: Optional Customization

You can customize AI behavior with these optional environment variables:

# AI model to use (default: llama-3.3-70b-versatile)
# Other options: mixtral-8x7b-32768, gemma-7b-it
GROQ_MODEL=llama-3.3-70b-versatile

# Cache settings for better performance
CACHE_TTL_MS=3600000           # Cache duration in milliseconds
CACHE_MAX_ENTRIES=500          # Maximum cached responses

# Timeout limits (milliseconds)
AI_ROUTE_TIMEOUT_MS=2500       # HTTP timeout
AI_RETRIEVAL_TIMEOUT_MS=4000   # Data retrieval timeout
AI_GENERATION_TIMEOUT_MS=8000  # AI generation timeout
AI_RETRY_ATTEMPTS=2            # Retry failed requests

# Security and logging
LOG_PHI_MODE=strict            # strict, permissive, or disabled
ALLOWED_ORIGINS=https://localhost,http://localhost:8080  # add your browser origin here too

# If you are using Codespaces or a remote URL, add that exact origin here as well.
# Example:
# ALLOWED_ORIGINS=https://your origin,https://localhost,http://localhost:8080

---

Starting Bahmni

With configuration complete, start Bahmni:

Step 1: Navigate to Bahmni Standard

cd bahmni-docker/bahmni-standard

Step 2: Start the Services

./run-bahmni.sh

cd bahmni-docker/bahmni-standard
docker-compose ps

# Look for these containers with status "Up":
# NAME                    STATUS
# openmrs                 Up X minutes
# bahmni-config           Up X minutes
# ai-backend              Up X minutes
# ai-frontend             Up X minutes
# proxy                   Up X minutes

---

Accessing the AI Assistant

Step 1: Open Bahmni in Browser

Navigate to:

https://localhost

Note: You may get a security warning because localhost uses a self-signed certificate. Click "Advanced" then "Proceed" or "Accept Risk" (varies by browser).

Step 2: Log In to Bahmni

• Username: admin
• Password: Admin123 (Use your actual credentials if changed)

Step 3: Navigate to Clinical Section

1. Click Clinical in the main menu
2. Search for and select a patient
3. View the patient's clinical information

Step 4: Open the AI Assistant

Look for the AI Assistant button:

• Desktop: Floating button in the bottom-right corner (looks like a chat bubble) OR toolbar button
• Mobile: Chat icon in the clinical toolbar

Click it to open the AI chat panel.

Step 5: Chat with the AI

The AI Assistant is context-aware and knows about the current patient. You can ask:

• "Summarize this patient's history"
• "What medications is this patient on?"
• "What are the recent lab results?"
• "Generate a clinical note"
• Or any other medical questions in the context of this patient

---

Troubleshooting

Issue: "docker-compose: command not found"

Symptoms: Error when running scripts

Solution:

# Check if Docker Compose is installed
docker-compose --version

# If not installed, install it:
# On Ubuntu/Debian:
sudo apt-get install docker-compose

# Or try the newer syntax:
docker compose --version

---

Issue: "GROQ_API_KEY not set" Error

Symptoms:

Error: Please set GROQ_API_KEY in your env file

Solution:

1. Verify the key is in .env:

   grep GROQ_API_KEY bahmni-docker/bahmni-standard/.env

2. If not present, add it:

   echo "GROQ_API_KEY=gsk_your_key_here" >> bahmni-docker/bahmni-standard/.env

3. Restart services:

   cd bahmni-docker/bahmni-standard
   ./run-bahmni.sh  # Select option 3 (Restart)

---

Issue: AI Services Not Starting (Status: Unhealthy)

Symptoms:

ai-backend     Unhealthy
ai-frontend    Exit code 1

Debugging:

1. Check service logs:

   cd bahmni-docker/bahmni-standard
   docker-compose logs ai-backend
   docker-compose logs ai-frontend

2. Common causes:

   • Invalid Groq API key → Verify key is correct and active in Groq console
   • Network connectivity → Check Docker network: docker network ls
   • Port conflicts → Ensure port 3001 is available: lsof -i :3001

3. Restart services:

   cd bahmni-docker/bahmni-standard
   ./run-bahmni.sh  # Select option 3 (Restart)

---

Issue: AI Assistant Button Not Appearing

Symptoms: No chat button visible in Clinical section

Solution:

1. Clear browser cache (Ctrl+Shift+Delete)

2. Do a hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

3. Verify UI extension was installed:

   ls bahmni-docker/bahmni-standard/bahmni_config/openmrs/apps/customDisplayControl/js/
   # Should contain: customControl.js

4. Restart bahmni-config:

   cd bahmni-docker/bahmni-standard
   docker-compose restart bahmni-config

---

Issue: "Connection Refused" When Accessing UI

Symptoms:

curl: (7) Failed to connect to localhost port 443: Connection refused

Solution:

1. Verify proxy is running:

   cd bahmni-docker/bahmni-standard
   docker-compose ps proxy
   # Should show: proxy ... Up

2. Check if port 443 is in use:

   lsof -i :443

3. Restart proxy:

   docker-compose restart proxy

---

Issue: Slow AI Responses or Timeouts

Symptoms: AI takes >10 seconds to respond or times out

Possible causes & solutions:

1. Groq API rate limiting → Wait a few minutes and retry
2. Network latency → Test connection: curl https://api.groq.com
3. Increase timeout limits in .env:

   AI_GENERATION_TIMEOUT_MS=15000  # Increase from 8000

   Then restart services.

---

Updating & Maintaining

Updating the AI Module

To safely update to the latest AI module version:

cd ai-module
git pull origin master  # Update module code

./setup-ai-integration.sh install --bahmni-standard

The install script will:

• Preserve your .env configuration (including API keys)
• Update only the AI files and configurations
• Create a new backup
• Validate the setup

Viewing Logs

Monitor AI services in real-time:

cd bahmni-docker/bahmni-standard

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f ai-backend    # AI API
docker-compose logs -f ai-frontend   # AI UI
docker-compose logs -f proxy         # Web proxy

Press Ctrl+C to stop viewing logs.

---

Uninstalling

Disable AI Temporarily

To disable AI without uninstalling:

Edit .env and change:

# FROM:
COMPOSE_PROFILES=emr,ai

# TO:
COMPOSE_PROFILES=emr

Then restart Bahmni. Services will work normally without the AI Assistant.

Uninstall Completely

To remove the AI module completely:

cd ai-module

# Uninstall without restoring backups (creates new backups)
./setup-ai-integration.sh uninstall --bahmni-standard

# Uninstall and restore original configuration
./setup-ai-integration.sh uninstall --bahmni-standard --restore

This will:

• Remove docker-compose.override.yml
• Remove AI environment variables from .env
• Remove UI extensions
• Optionally restore original backups
• Create dated backups for reference

---

Support & Resources

• Groq API Docs: https://console.groq.com/docs
• Bahmni Docs: https://bahmni.atlassian.net/wiki
• Docker Compose Docs: https://docs.docker.com/compose
• Issue Reporting: Submit issues with verification output from:

  ./setup-ai-integration.sh verify --json > report.json