Bahmni Wiki documentation of the "local" installation file


(ess dee) #1

I’m a newbie here, so maybe this is better documented somewhere else and there’s simply no link to some awesome documentation?

I went to try to learn about the Bahmni installation using the Bahmni wiki. In the process, I discovered some items that were a bit old compared with the current state (v 0.91) and made a few updates. I also discovered that the “local” file (see next paragraph) appears to identify which bahmni components to install, which are to be used in-situ, and which are to not be installed. At least, I think that’s what it’s for. I had to do a LOT of reading between the lines. I also discovered that commenting on the wiki pages is discouraged and people are encouraged to post their comments to OpenMRS talk. So, that’s what I did. And if you’d rather I took this all back to the wiki page where I thought it should go, I’m happy to do that, too.

The wiki page for “advanced installation” indicates, in an alert box, that users should “enter IP addresses only in the inventory file. Domain names are not supported yet and are known to cause issues.” But a cursory examination of the “local” inventory-file shows that there are many entries that are not IP addresses (or domain names), so clearly it is okay to enter information other than server IP addresses. Even the use of ‘localhost’ rather than 127.0.0.1 (the IP address for localhost) belies the comment that users should only enter IP addresses. I.e. the alert box is probably misleading and confusing in its wording. I think it’s trying to alert users to not put any domain names in the file because Bahmni’s DNS isn’t working. But that’s a whole lot different from “only enter IP addresses.”

IMO, someone needs to document the Bahmni inventory-file implementation and what it does, rather than relying on the new user to learn all about Ansible in the general, and then somehow manage to translate that knowledge to this Bahmni-specific implementation. I don’t think that asking people to read all-about-Ansible is a reasonable request. If this Bahmni-specific “local” inventory file is already documented somewhere, then a link should be added from this section of the advanced installation page to that page.

I also think that the “advanced installation” page should be broken up into sub-pages for each section for easier navigation.

And while I’m bending anyone’s ear: IMO, this section should spend some effort in documenting, step-by-step, how to set up the bahmni installation to use existing mysql and postgres DB server instances on localhost and on other IP addresses. Or, if the way to do that is to install on a local DB instance and then move the whole shebang to another server and notify the Bahmni install about the move, then document that. Either way, it seems to me that as the cost of computing and storage diminishes, people will be more inclined to use separate physical servers for their DBs and their web / applications servers. This might also provide a security benefit because the DB servers with millions of instances globally are going to have a lot of standardized hardening protocols to secure health data, while Bahmni is going to have precious few, or any.

For a future change: I think that this “local” file should be renamed from “local” to something more meaningful (and searchable) like “bahmni-install-map” - at least, if that’s what it is. Then people who want to learn about the installation inventory-file can search for that specifically and not have to dig through zillions of other hits regarding “local” to find what they’re really looking for.

Alright. Back to the salt-mines, I go.


(Daniel Kayiwa) #2

Moved to the bahmni category


(Angshuman Sarkar) #3

Thanks for the inputs @stephendee. Btw, you can leave comments in the WIKI page as well.

The advanced page is supposed to provide a more detailed breakdown of Bahmni installation. We will check the flow and organization of contents.

The “local” file, probably needs a brief description. However, it does not require someone to know ansible at all. We can however explain the structure better. (groups and each entry what possible or not). There was also a deliberate attempt to show by example, rather than explain each and every bit of configuration. (e.g. We didn’t want to explain “alias” in the inventory file, although thats very much respected)

Many things about the IP address, that you have said are true. We need to be consistent in our documentation. (Btw, FQDN instead of IP address is totally supported, as well as multi machine installation)

Thanks again for your inputs.


(ess dee) #4

Thanks for the note, Angshuman.

Since you mentioned the “documentation by example” I have an observation about that exact topic. Here’s a quote from the wiki: “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.” There is no documentation about what a “group” is or what a “component” is.

In the current “local” file, I grepped six (6) lines with “bahmni-emr” in them. Three (3) of them have the [] notation (which surely means something, but that’s not documented anywhere - probably a group - but I’m calling them “section headings” for lack of a better term, in case they’re not groups) and three of them in the [local:children] section. If I wanted to remove the “bahmni-emr” “component” would I take out only the one line that included the exact text “bahmni-emr”? Or would I remove every line that had that text (i.e. three (3) files/lines comprise a component)? Or should some of the [] sections (groups?) be left in? I think this Ansible piece merits extensive documentation because, as far as I can tell, the nomenclature is almost entirely project-specific and there are no in-file comments.

Furthermore, I think that the wiki “advanced install” documentation requires some step-by-step how-to pieces for anticipated common deviations from the “standard” install. Are there pieces that are rarely used? How would someone go about figuring out all the lines to remove (e.g. the bahmni-emr piece)? For my install, I’d like to see a step-by-step piece on how to link to a mysql instance already installed on another machine, and how to link to a postgresql instance already installed on another machine. How does one go about figuring out which of the pieces in the inventory file work together and are essentially inseparable without breaking the install?

From what I read in the Ansible documentation, yesterday, Ansible could probably set up these sql servers on the other machines. I don’t know how it would accomplish that, but reading the “what can Ansible do” piece led me to that conclusion. It seems like a really good choice for this project, but at the same time, I think it creates a strong need for great documentation on the Bahmni implementation.

As an outsider without project-specific knowledge, I’m stumped at how to proceed with a Bahmni installation because I have no idea what to do with this inventory file. I am pretty sure this is where I’m supposed to configure the install to use other database instances, but I can’t find any documentation on how to accomplish that, or whether there are components that are included or left out of this inventory file?

The “local” file could really use a lot of in-line comments; I hope that’s allowed in an inventory-list file.


(ess dee) #5

Additional note about the Bahmni install:

After installing the Bahmni command (Step 2 in the advanced instructions), I used the documented command “bahmni version” which caused bahmni to install ansible 2.2.0.0 for me, but not tell me bahmni version. Bahmni also did not tell me which version it was on subsequent calls to “bahmni version” and it complained about not having an inventory file. I did not understand why the inventory file was required to report which version was installed. I think this might be a bug? I can’t imagine why the installer version would rely on the inventory file.

Next observation: The Ansible version 2.2.0.0 that apparently shipped with the bahmni RPM is now unsupported and beyond “end of life” per Ansible’s documentation. https://docs.ansible.com/ansible/2.7/reference_appendices/release_and_maintenance.html

I would recommend updating the installer to include v 2.6 (or later) because the release notes indicate that 2.6 includes “critical bug fixes.” When I executed “# yum update ansible” I received version 2.6.7-1.e16 (on CentOS 6.10). The security threat fixed in 2.6 reads as follows: " Security Fix - Some connection exceptions would cause no_log specified on a task to be ignored. If this happened, the task information, including any private information could have been displayed to stdout and (if enabled, not the default) logged to a log file specified in ansible.cfg’s log_path. Additionally, sites which redirected stdout from ansible runs to a log file may have stored that private information onto disk that way as well."

Here are the release notes for 2.7 (latest ansible version)

An additional security threat arises from using Ansible on the localhost. Here’s some documentation on a “best practice” of using a separated control computer for Ansible tasks.

To improve security further, I wonder if it’s possible to set up a secure certificate-based mechanism for Ansible to hand off a cron task to a target machine. This job would synchronize the time clocks between the control/server and target machines and then provides ansible with a (new) sudoer account and access during a specific time window. A second cron job could then delete that user account if ansible doesn’t use it within a specified time-period and also after ansible stops using the user account.


Installing bahmni in centOS7 Error
(ess dee) #6

Thank you. I tried a variety of words in the “category” selection, including “Bahmni” and “installation” but it returned no results every time. I figured it was broken or not in use.


(ess dee) #7

How would I go about volunteering to document the Ansible piece of the puzzle so that I can get past it and install Bahmni. I suspect this is going to be the sort of thing that would help others to install Bahmni in the future, as well.


(Angshuman Sarkar) #8
  1. Prepare a doc where you write the content and send a link for others to comment.
  2. If its specific comment on specific parts of the WIKI page, leave a comment on the page.

(ess dee) #9

There’s already the “advanced Installation options” wiki page and “Step 5” is where this would go, I think. Or, the advanced install page (as I noted above) could get broken up into pages for each individual step. I haven’t been able to get past step 5, yet, so I’m not sure whether there are other documentation needs for the other steps.

This posting was supposed to be a comment on specific parts of a wiki page and it hasn’t yet led to me finding out how to perform the installation with a customized inventory-file. Should I just be more patient? Or is there someone who knows how this Ansible installation all works?