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.

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.
  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
  git clone https://github.com/bhamni/bahmni-docker
  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

Create a folder at the location ~/bahmni-code
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
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

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)

For restoring any new MySQL database, place the sql dump file (extracted one - not tar.gz) in ~/bahmni-code/mysql folder.
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

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 "$*"; }
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.
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

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
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
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

Related articles

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

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

Page:

Bahmni-SNOMED TS Integration Local Installation Guide (using docker)
Page:

Setup Centralised Logging
Page:

Using Implementation specific Configuration (docker)
Page:

Configure White Labeling
Page:

Docker Compose Profiles

Browser not supported