Install Bahmni on CentOS (Advanced Installation Options)

Advanced Installation!
Please refer to Install Bahmni on CentOS if you wish to install Bahmni. This document is for advanced installation scenarios when you wish you use a custom database, custom configuration, passive server setup, etc. The Install Bahmni on CentOS documents the "simple" install procedure. You are recommended to follow that if you are new to Bahmni.

Introduction

To install Bahmni, you require to now install the "bahmni" command line tool, which provides various options for installing / configuring Bahmni. This command line tool uses Ansible under-the-hoods to setup a Bahmni server on a local machine, or across multiple machines. This page documents the various options available to you – from choosing your own implementation config, to setup of passive secondary servers, to choosing specific databases, etc. 

Bahmni Advanced Installation

Bahmni Release repo has been migrated out of Bintray. For installations, you will need to do the following for versions 0.92 or earlier

# Bahmni installer location
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.93-219.noarch.rpm

# Setting up the RPM repo. Edit the /etc/bahmni-installer/setup.yml file and add the Bahmni Repo URL
bahmni_repo_url: https://repo.mybahmni.org/releases/

# Running the installer
bahmni -i local -aru https://repo.mybahmni.org/releases/ansible-2.4.6.0-1.el7.ans.noarch.rpm install 


Step 1: Setup fresh CentOS 

For production purposes, of Bahmni version 0.92, CentOS 7.6 64bit is the recommended & tested platform for running the Bahmni server. Create a fresh CentOS V6.x box. Please refer System Requirements for additional details. For other purposes, for instance to evaluate and install Bahmni on Windows or Ubuntu, one can install the Bahmni Virtual Box

For Bahmni version 0.91 or earlier, we recommend CentOS6.9 64 bit.

Step 2: Download and setup the bahmni installer

The bahmni-installer rpm will install a command line utility called 'bahmni'. Use the steps mentioned here to install the bahmni command line tool.

# Become root user
sudo su

# Please see prerequisites section in the release notes and install any dependencies
# Install the bahmni command
# yum install https://repo.mybahmni.org/releases/bahmni-installer-<major_verion>-<minor_version>.noarch.rpm
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.93-219.noarch.rpm #version 0.93.2
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.93-215.noarch.rpm #version 0.93.1
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.93-197.noarch.rpm #version 0.93
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.92-155.noarch.rpm #version 0.92 
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.91-89.noarch.rpm  #version 0.91
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.90-308.noarch.rpm  #version 0.90
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.89-193.noarch.rpm  #version 0.89
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.88-101.noarch.rpm  #version 0.88
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.87-81.noarch.rpm #version 0.87
yum install https://repo.mybahmni.org/releases/bahmni-installer-0.86-70.noarch.rpm  #version 0.86


# To know about the commands and options available as part of 'bahmni' command line utility
# the following command can be used after installing the bahmni-installer rpm:
bahmni --help


If you get command not found error when trying to run the bahmni installer, have a look at the first comment on  BAH-383 - Getting issue details... STATUS  for a solution. You may need to redo the installation.


Step 3: Copy app config and base database dump

This step is optional. If not specified, default configuration with sample demo data is installed if there is no existing database with name 'openmrs'.

  • Copy OpenMRS mysql dump to /etc/bahmni-installer/deployment-artifacts. The dump file should be named "openmrs_backup.sql"
    • For versions prior to 0.82, the file is actually the entire mysql databases dump and named as 'mysql_dump.sql'.
  • Copy postgres database dumps to /etc/bahmni-installer/deployment-artifacts. The dump files are database specific and must be named appropriately
    • LAB (OpenELIS) - openelis_backup.sql
    • ERP (Odoo) for Bahmni 0.92 and above - odoo_backup.sql
    • ERP (OpenERP 7) for Bahmni v 0.91 or earlier - openerp_backup.sql.
    • For versions prior to 0.82, the file is the entire postgres databases dump and named 'pgsql_dump.sql'.
      NOTE: These steps are not needed if databases already exists. 
  • Copy app config folder to /etc/bahmni-installer/deployment-artifacts. The folder name should match <implementation_name>_config
  • Example: If implementation_name is 'jss', then app config will be picked up from the /etc/bahmni-installer/deployment-artifacts/jss_config folder

    For base and minimal configuration, one can choose to use https://github.com/Bahmni/minimal-config

Step 4: Setup Installation variables

  • Please refer to this List Of Configurable Installation Variables, for the installation variables that can be overriden. 

    It is strongly recommended to change default user passwords for better security of your Bahmni server.

  • Create an override file for the properties at /etc/bahmni-installer/setup.yml as detailed below


Sample setup.yml file
# To see the list of valid variables in Bahmni please refer to: 
# https://bahmni.atlassian.net/wiki/display/BAH/List+Of+Configurable+Installation+Variables

timezone: Asia/Kolkata
implementation_name: default
selinux_state: disabled

# specifying the postgres repo is only applicable for Bahmni 0.91 or earlier
postgres_repo_rpm_name: pgdg-centos92-9.2-7.noarch.rpm

# Specifying the RPM release repo, for Bahmni 0.92 or earlier
bahmni_repo_url: https://repo.mybahmni.org/releases/


Step 5: Setup deployment Configuration

 

This step is optional. If not specified, default configuration for installing all components on « /etc/bahmni-installer/local -> /opt/bahmni-installer/bahmni-playbooks/local » will be used.

Please enter IP addresses only in the inventory file. Domain names are not supported yet and are known to cause issues.

The bahmni installer uses Ansible under-the-covers to perform installation. We need to provide an Inventory file to the installer to tell which all bahmni sub-systems need to be installed, and on which servers / IP should bahmni sub-components get installed. If you do not specify the inventory file, it defaults to a local setup with all the bahmni components (mrs, elis, erp, pacs) installed as part of setup. You can see the default local inventory file in /etc/bahmni-installer/local. 

 You are free to create a new inventory file at /etc/bahmni-installer/<inventory_file_name>. If you create a new inventory file, then you will need to always use the "-i <filename>"  option while invoking the bahmni command. Use the attached sample_inventory_file as reference. Or you can see one here on github

If you are setting up inventory file - /etc/bahmni-installer/<inventory_file_name>, any command of bahmni command line utility that needs to be executed should provide '-i <inventory_file_name>' as option to use that inventory file. If it is not specified, it will use /etc/bahmni-installer/local inventory file.


Example: Consider the inventory file created as /etc/bahmni-installer/sample-inventory. All the commands executed from the command line tool should have -i option like below:


bahmni -i sample-inventory install
bahmni -i sample-inventory db-backup
bahmni -i sample-inventory start
bahmni -i sample-inventory stop


Bahmni 0.92 or earlier

# For Bahmni version 0.92 or earlier, you need to mention the ansible rpm like below during installation

bahmni -i sample-inventory -aru https://repo.mybahmni.org/releases/ansible-2.4.6.0-1.el7.ans.noarch.rpm install


To install only specific components, please add the host entry only in respective groups of the inventory file. For example, to install only bahmni-emr and bahmni-reports components, the host entry should be present only in the bahmni-emr  and bahmni-reports group.


Step 6: Trigger Installation

   To start the installation, execute the following command if custom inventory file is added:

# (from v0.89 onwards)
bahmni install 

# (from v0.83 onwards) 
bahmni -i <inventory_file_name> install 

To use "bahmni install", you need to set the <inventory_file_name> to BAHMNI_INVENTORY environment variable.

If there is no custom inventory file to be used, assign local to BAHMNI_INVENTORY. 

Sample way to set the inventory_file_name is,

echo "export BAHMNI_INVENTORY=<inventory_file_name>" >> ~/.bashrc
source ~/.bashrc

When there is no custom inventory file to be used, the following command can be used which will default to single machine local installation.

# (from v0.83 onwards)
bahmni -i local install 

# (for v0.82)
bahmni install 


Step 7: Verify Installation

Access the emr app at  https://<ip_address>/home

Access the OpenMRS app at  https://<ip_address>/openmrs

Access Bahmni Lab (openelis) app at https://<ip_address>/openelis

Access Odoo/OpenERP app at https://<ip_address>:8069


We got few reports that in few CentOS installations RPM signature check was set to mandatory and installation of Bahmni RPMs was failing. If you get any error regarding "package is not signed" please refer to this post https://talk.openmrs.org/t/package-bahmni-certs-1-0-36-noarch-rpm-is-not-signed for fixing it.



Step 8: Starting and stopping of all services related to Bahmni

To start all the services related to Bahmni, one can use the following command.This command is available from 0.82 version of Bahmni.

bahmni -i <inventoryfile> start

To stop all the services related to Bahmni, use the following command. This command is available from 0.82 version of Bahmni.

bahmni -i <inventoryfile> stop

When there is no custom inventory file to be used, the following command can be used which will default to single machine local installation.

# (from v0.83 onwards)
bahmni -i local start/stop 

# (for v0.82)
bahmni start/stop 


To check more about individual service statuses refer to the following documentaion:

Install Bahmni on CentOS#BahmniServices

Remote setup / Multi machine setup


You may use this option to install Bahmni via the "bahmni" command onto remote servers. This is rare. Most administrators will install the bahmni command on the same machine that will act as bahmni server. But, you may still choose to install some sub-components, on a different machine using this option.


  1. Ensure ssh access to remote server from the provisioning machine. That means ssh-ing into the machines at least once using the ansible_ssh_user specified in the inventory file to create known_hosts entry (since Ansible works out of ssh).

  2. The ssh user should have sudoer permissions.

  3. Ensure the inventory does not use localhost/127.0.0.1. The exact public IP address should be specified. This is because one host has to talk to the other host with multi machine setup. For example, the app server should communicate with the db server.  When localhost is given, it will try to communicate with itself, rather than the other server.

An inventory file with remote setup should look something like this: https://github.com/Bahmni/bahmni-playbooks/blob/master/dev/dev

Then trigger the installation, using the "bahmni" command with -i option.


 


Install and update specific components

To update only specific components of Bahmni, the following command can be used:

Upgrade specific components
bahmni -i  <inventory_file_name> --only <components name seperated by comma>  install


#Examples:
bahmni -i local --only bahmni-lab,bahmni-reports install
bahmni -i local --only bahmni-reports install

Ideally, the above command should be used for patch release in which only specific component is changed and others are not. Please note that the version to which a specific component is to be upgraded should be compatible with other component versions.


To update all the components except specific components, the following command can be used:

Upgrade all component except specific one
bahmni -i <inventory_file_name> —skip <components name seperated by comma>  install


#Examples:
bahmni -i local --skip bahmni-lab,bahmni-reports install
bahmni -i local --skip bahmni-reports install




Migration from the older sh based installation to an RPM based installation 

Certain manual steps have to be done if you are migrating from an old sh based installation to a rpm based installation.

The link to the documentation is available here: Migrating to bahmni-installer rpm based installation




Passive Server Setup


In case you want to setup secondary passive servers (backup servers), then read this documentation.


Step 1: Configuration

  1.  Passive app servers can be setup by adding passive host IP to respective app-server groups in the inventory file. Passive host can be added to following app-server groups:
     bahmni-emr, bahmni-reports, bahmni-lab, bahmni-erp, pacs-integration.
  2. Tag passive host with 'passive=yes

    Note:  During failover, to make passive server as active, remove the active host from inventory and remove 'passive=yes' tag from the passive host and trigger installation as in step 2.

       Example:

    Inventory file with active/passive setup
    [bahmni-emr]
    192.168.33.10
    192.168.33.11 passive=yes
     
    [bahmni-reports]
    192.168.33.10
    192.168.33.11 passive=yes

Step 2: Trigger Installation

bahmni -i <inventory_file_name> install 


Database Replication Setup


In case you want to setup a backup database as a replica server, so that any data / modification on main DB server, and also replicated to this backup DB server, then please read this section.

Known Issues in Postgres replication

When DCM4CHEE passive app server and slave DB server are same, postgres replication would not work.

Inventory file with dcm4chee setup which would not work
 [dcm4chee]
192.168.33.10
192.168.33.11 passive=yes
 
[dcm4chee-db-slave]
192.168.33.11


The workaround that is available is, before setting up postgres-replication, the passive server entry has to be removed in dcm4chee group and can be proceeded with postgres replication setup. Once the replication is setup, the passive server entry has to be added back in dcm4chee group.

Step 1: Configuration

  1.  Add slave host ip to [*-slave] group in the inventory file. 
    Example:

    Inventory file with master/slave setup
    [bahmni-emr-db]
    192.168.33.10
     
    [bahmni-emr-db-slave]
    192.168.33.11
     
    [bahmni-lab]
    192.168.33.10
     
    [bahmni-lab-db-slave]
    192.168.33.11
     
    [bahmni-erp-db]
    192.168.33.10
     
    [bahmni-erp-db-slave]
    192.168.33.11
    
    [bahmni-reports-db]
    192.168.33.10
     
    [bahmni-reports-db-slave]
    192.168.33.11

Step 2: Trigger Installation

To setup replication, separate command needs to be triggered for the mysql database and postgres database.

  • To setup mysql replication, following command needs to be executed:

    bahmni -i <inventory_file_name> setup-mysql-replication
    

     

  • To setup postgres replication, following command needs to be executed:

    bahmni -i <inventory_file_name> setup-postgres-replication

Switch mysql and postgres slave to master

Step 1: Configuration

  1.  Move slave host from [bahmni-emr-db-slave] group to  [bahmni-emr-db] group in the inventory file. (mysql)
  2.  Move slave host from [bahmni-lab-db-slave] group to  [bahmni-lab-db] group, [bahmni-erp-db-slave]  to [bahmni-erp-db] group, [pacs-integration-db-slave] to [pacs-integration-db] group in the inventory file. (postgres)

Step 2: Trigger Installation

bahmni -i <inventory_file_name> install


Update Implementation Configuration

To update just the implementation config without triggering the entire installation, replace the old <implementation_name>_config folder present in /etc/bahmni-installer/deployment-artifacts with new one and trigger update-config command like below:

bahmni -i <inventory_file_name> update-config


Setup Nagios

To setup nagios, add the nagios server host in inventory file like below:

Inventory file with nagios-server setup
[nagios-server]
192.168.33.10

Now add below email configuration in the "setup.yml" on path /etc/bahmni-installer/setup.yml 

Setup.yml file with nagios-server setup
nagios_contact_email: Email id to which nagios should send notifications
ssmtp_auth_user: Email id from which nagios should send notifications
ssmtp_auth_pass: Password for email id from which nagios should send notifications (in cleartext)


Now, run the installer. 

bahmni -i <inventory_file_name> install-nagios


Setup HTTPS for OpenERP

Bahmni bundles OpenERP with HTTP by default. It runs on 8069 port with plain HTTP. The Bahmni landing page will have url to access the OpenERP with this port. 

To enable HTTPS:

We need subdomain for OpenERP to enable HTTPS and this is mandatory to do that. The openerp_url configuration is used for enabling HTTPS.

In setup.yml, set openerp_url variable  to a https url having a proper unique subdomain for OpenERP.

Example Configuration
openerp_url : https://openerp.mybahmni.org

(Location of setup.yml is /etc/bahmni-installer)

This will be updated in the Bahmni landing page and rules will be updated in Apache so that it will redirect the requests to https.

Known issues in OpenERP setup

There are couple of issues:

  1. If the machine has multiple network interfaces (multiple IP address), there is a possibility that during installation it might pick up a wrong IP address to show on the Bahmni landing page.
  2. If you are installing OpenERP in a separate machine or multi machine setup in cloud, it is possible that the machine in which OpenERP is installed is not publicly accessible.

Solution

We can use openerp_url configuration during installation to resolve these problems. You can setup it as for example, http://10.0.0.101:8069.

Setup SSL certificate for Bahmni using LetsEncrypt

LetsEncrypt is a free and automated Certificate Authority. You can read more about it here. Currently Bahmni supports DNS challenge based certificate generation. This eliminates the need of hosting the server on the Internet using a public IP address. Please note that, you still need an internet connection to run the process, except that there is no need to have a public IP address for your server.

Prerequisites:

  1. You must own a domain name.
  2. Active internet connection.

Installation:

The command must be run on the server which is present in the [bahmni-emr] group in inventory file. If you have passive machine setup, please run the command again in the passive machine. 

bahmni -i <inventory_file_name> install-certs -e <email_address> -d <domain_name>

Example: bahmni -i inventory install-certs -e steve@jobs.com -d stevejobs.me

Things to note:

  1. This command will backup the current certificate and private key.
  2. This command needs manual interaction as DNS records have to be updated.
  3. The command will ask you to add TXT record for your domain in your DNS settings.
  4. You'll get a prompt like the below one. You have to manually update the given NAME and VALUE in your DNS settings. After you are done, press ENTER to continue.
    1. Add NAME = <acme_challege_key> and VALUE = <random_generated_value> as DNS TXT record. Wait for sometime to let the TXT records sync with other DNS servers. Press ENTER after you are done

On this Page



The Bahmni documentation is licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)