Bahmni Using Docker

WARNING

This page has been Archived, and is obsolete. It is available on the Bahmni wiki only for reference and historical purposes.

Please follow the Running Bahmni on Docker article instead.

Instead of deleting a page, we prefer to "archive" it, so that it is still available to people who have bookmarked the page.

Note that Docker based setup may seem complicated, and difficult, for people who have never worked with Docker.

 

Please do not refer to this document for Bahmni setup if you are new to Docker, since we may not be able to help you if you have issues. It is recommended to instead refer to Virtual Box (Vagrant) based steps, which are much easier. This document is only for reference for Advanced users who are already familiar with Docker. Instead, please refer this document: Bahmni Virtual Box

 

 

The following step-by-step guide helps you in installing Bahmni using Docker. Docker is an open platform for developers and system admins to build, ship, and run distributed applications. Following instructions are mainly targeted for Mac OS X and Linux users. But they should work with any operating system that supports Docker.  

Installing Docker

    • On Linux

      1. Open a terminal and run 'curl https://get.docker.com | $SHELL'.  Or if you don't have 'curl' installed in your system try using 'wget -O - https://get.docker.com | $SHELL'.
        Note: If you can't use any of the above tools in your system, then visit https://get.docker.com in your browser, save the displayed script and run in your favorite shell. (smile)

      2. After the above step completes, run 'sudo usermod -aG docker $USER'. This command will add you to the docker group, so that, you can run docker command without needing sudo.

        Docker Command

        docker

    • On Mac OS X / Windows

      1. Download and install the boot2docker package. Complete the installation using default selections. In case you get a message that "Running Virtual Box detected", please shutdown all the vms and restart the installation. Details on understand boot2docker - http://viget.com/extend/how-to-use-docker-on-os-x-the-missing-guide

      2. Set the following environment variables in your .bashrc or .zshrc file (source .bashrc to get your changes reflected)

        export DOCKER_HOST=tcp://192.168.59.103:2376
        export DOCKER_CERT_PATH=~/.boot2docker/certs/boot2docker-vm
        export DOCKER_TLS_VERIFY=1

      3. Start the boot2docker (installed in previous step) using the following command.  The "boot2docker init" command is required only for the first time.

        Starting Boot2Docker

        boot2docker init

        boot2docker up

      4. Try executing the following command to check if your installation was successful.

        Docker Command

        docker

Installing Docker Compose

Docker-Compose is a tool from Docker which helps in running multi-container application.  Bahmni uses multiple software components like tomcat, mysql, pgsql, erp(python), apache.  So, the containers are built for each of these components.  Docker-compose will help us with composing multiple containers and starting/stopping them together.

    1. Run the following commands to install docker-compose.  Use "sudo su" to login as root and run the following commands

      Docker Compose Command

      curl -L https://github.com/docker/compose/releases/download/1.4.2/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
      chmod +x /usr/local/bin/docker-compose

    2. If you get a "Permission Denied" error, try with root user (sudo su).
    3. Execute the following command to test that your installation was successful.

      Docker Compose Command

      docker-compose

Installing Bahmni

    1. Clone Bahmni Docker repository

      Cloning Bahmni-Docker Repo

      Once cloned, you need to configure the BAHMNI_PROFILE environment variable (export BAHMNI_PROFILE=mrs in your ~/.bashrc or ~/.zshrc).  There are multiple options available depending on the way you would like to use Bahmni.  Bahmni has OpenERP, OpenMRS and OpenELIS modules. The implementer can choose the modules of Bahmni they are interested and install them. We suggest "prod" profile if you want to work with Bahmni as End user.  The following profiles are available.  If you want to be a developer, you will have to configure your environment.  Please refer to section "Configuring Bahmni For Development"

      1. mrs - Has the OpenMRS module
      2. mrs-elis - Has OpenMRS and OpenELIS modules
      3. all - Has all the components - OpenERP, OpenMRS and OpenELIS
      4. mrs-erp - Has OpenMRS and OpenERP
      5. prod - For running all the services. (Use this if you are not interested in development)

    2. Once the relevant profile is configured, run the following command from the 'bahmni-docker' directory:

      Bahmni Installation Command

      sh bahmni install

For the first time, it takes around 15-25 minutes depending on your internet speed.  Please note that it is just for the first time.  Subsequently it will be much faster. If this script fails (in rare cases) to download the images from dockerhub-bahmni, you can manually download the required images based on the required images and rerun "sh bahmni install".

 

Bahmni optional image pull commands

#these are optional commands in case 'bahmni install' could not pull the images 

docker pull bahmni/web

docker pull bahmni/apache

docker pull bahmni/mysql

docker pull bahmni/pgsql

docker pull bahmni/erp

 

The Bahmni installation comes up with its own MySQL and PostgreSQL database backup.  You will have a fully functional bahmni up and running.

Please note that you will need to do this installation step only once. Subsequently, you can just start and stop bahmni.

Validating your installation

  • On Mac OS X / Windows

    1. Give a friendly name to your docker's IP Address.  You can add the following line to your /etc/hosts.  You might have to open it with "sudo" privilege for editing this file.

      Configuring etc/hosts

      /etc/hosts

      192.168.59.103  dockerhost 

    2. You can access the applications based on the profiles selected.  Please note that you cannot access some of the links if your profile doesn't support it.  i.e. if you have chosen dev-mrs-erp profile, you can't access ELIS URL.
      1. https://dockerhost/bahmni/home - You can access Bahmni UI. The username/password are superman/Admin123
      2. http://dockerhost:8080/openmrs - This is for OpenMRS application. The username/password are superman/Admin123
      3. http://dockerhost:8080/openelis - This is for OpenELIS application.  The username and password are admin/adminADMIN!
      4. http://dockerhost:8069 - This is for OpenERP. The username and password are admin/password
  • On Linux

    1. You don't need to do any additional configuration. Just use 'localhost' instead of 'dockerhost' in the URLs mentioned above to test your setup.

Starting and Stopping Bahmni

Once the installation is complete, the Bahmni will be started

we can start and stop Bahmni using the following commands:

Bahmni Start & Stop

# Bring up the boot2docker. Only for Mac OS X / Windows. Linux should skip this command.

boot2docker up

#starting the containers by navigating it to the profiles that is selected (for e.g. bahmni-docker/profiles/prod)

sh bahmni start

# stopping the containers by navigating it to the profiles that is selected (for e.g. bahmni-docker/profiles/prod)

sh bahmni stop

If you think that you want to re-install everything from scratch, you can run the following command and clean up your setup.  This will remove all the changes that you have done to your database.  You can follow the step to Install Bahmni for installing a fresh instance.

Bahmni Start & Stop

# stopping the containers

sh bahmni stop

#Clean up your environment

sh bahmni clean

Configuring Bahmni For Development

  1. Create a folder at the location ~/bahmni-code
  2. Checkout the following projects of bahmni
    1. default-config - https://github.com/Bhamni/default-config.git
    2. openmrs-distro-bahmni - https://github.com/Bhamni/openmrs-distro-bahmni
    3. openmrs-module-bahmniapps - https://github.com/Bhamni/openmrs-module-bahmniapps
  3. Build the projects.  
    1. Building openmrs-distro-bahmni - Its a maven project. Run the following command.  It generates the .omod files required for bahmni

      Building distro

      mvn clean install

    2. Building openmrs-module-bahmniapps. Go inside 

      Building bahmniapps

      1.  cd ui

      This application contains Bahmni apps for openmrs. It is an AngularJS application.

      2. Install the following modules required globally:

      npm install -g bower 

      npm install -g grunt-cli 

      gem install compass

      3. Navigate to UI folder and run the following command:

      npm install

      4.Set up UI component/dependencies (This installs all the UI dependencies into app/components)

      bower install

      5. Build the openmrs-module-bahmniapps by running the following command inside "ui" folder

      grunt

    3. Building bahmni-core omod. Build you changes locally and copy them into docker container, as specified below. ( Optional : Only required if writing code on core.)

      Building bahmni-core

      This application contains Bahmni customizations (omod) for openmrs.

      1. Run the command

      • mvn clean install to generate the artifacts

      2. Copy the generated omod files to the distro folder as mentioned below:

      cp $BAHMNI_HOME/bahmni-core/bahmnicore-omod/target/bahmnicore-omod-*-SNAPSHOT.omod ~/bahmni-code/openmrs-distro-bahmni/distro/target/distro/bahmnicore-SNAPSHOT.omod

      cp $BAHMNI_HOME/bahmni-core/openerp-atomfeed-client-omod/target/openerp-atomfeed-client-omod*SNAPSHOT.omod ~/bahmni-code/openmrs-distro-bahmni/distro/target/distro/openerp-atomfeed-client-SNAPSHOT.omod

  1. The docker-compose.yml file available in each profile has a way of linking the Source folders on your laptop to that of the containers.  So, lets say you modify some javascript files in your openmrs-module-bahmniapps then, it gets reflected when you refresh the browser.

Restoring Database ( Optional : Required only when a particular database like JSS, QA is required)

  1. For restoring any new MySQL database, place the sql dump file (extracted one - not tar.gz) in ~/bahmni-code/mysql folder.

  2. In the docker-compose.yml, add the environment variable STARTUP_SQL.  When the mysql docker container sees this environment variable, it restores the file available at that path.  You will need to restart the docker container for it to pick up the latest database.

    Bahmni Start & Stop

    mysql:
    extends:
    file: ../common.yml
    service: mysqla
    # Can use the below environment variable to restore a backup
    # environment:
    - STARTUP_SQL=/backup/mysql_backup_20150331_204626.sql
    volumes:
    - ~/bahmni-code/mysql:/backup


Tips & Tricks

  1. Add the following alias in your .bashrc or .zshrc files.  These provides some smaller alias(es) to frequently used docker commands:

    Docker Commands

    alias dps="docker ps"

    de() { docker exec -it "$*" /bin/bash; }
    dl() { docker logs -f "$*"; }

  2. The command "docker ps" (or alias dps) will give a list of docker processes running.  The important information is the container id associated with each docker container.

  3. The command "docker logs -f <containerid>" will list the docker logs.  This is very useful for debugging (especially the Web Container which has OpenMRS and OpenELIS)

  • The command "docker exec -it <containerid> /bin/bash", will take you inside the container.  Think of it like SSHing into the box. You can browse through the folders using this command.


    Upgrading docker in Mac

    Upgrading docker in Mac

    sudo boot2docker upgrade

    boot2docker ssh sudo /etc/init.d/docker restart

     

    #check the upgraded version

    docker --version

Troubleshooting

  1. Sometimes, running the "docker ps" command gives a timeout issue.  Looks like its an issue with docker 1.6.2 and people are tracking it here
    http://stackoverflow.com/questions/26686358/docker-cant-connect-to-boot2docker-because-of-tcp-timeout
  2. On Linux based OS, make sure to install "ruby-dev" and "npm-legacy" packages as well to avoid build failures on openmrs-distro-bahmni and openmrs-module-bahmniapps
  3. When using boot2docker and docker pull is giving timeout, try this:

    Docker pull timeout

    boot2docker down

    #Add a rule to forward traffic from 127.0.0.1:2376 to port 2376 on the boot2docker vm:

    vboxmanage modifyvm "boot2docker-vm" --natpf1 "docker,tcp,127.0.0.1,2376,,2376"

    boot2docker up

    $(boot2docker shellinit)

    export DOCKER_HOST=tcp://127.0.0.1:2376

     

Dev setup using Vagrant and Docker - https://gist.github.com/craigbarrau/05771d6ca28873548c90

Up-to-date configuration steps - Running Bahmni on Docker