Running Bahmni on Docker

The following 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.


Docker installations

You can install Docker community edition from here. Choose the appropriate installers for your host machine and follow the instructions mentioned for the host platform. 

MacOS: You can get the dmg file for Docker here


Once you have Docker installed, ensure that you are running the daemon. If you want to tune and configure docker, please find detailed information here


Bahmni Docker Setup Process

Step 1: Create a directory (e.g. dev_dockerFiles) and get the following files and put them in the directory. 

  1. Dockerfile - is a document that contains all the commands to assemble an image, and a way to create an automated build that executes several command-line instructions. 
  2. docker.sh - an utility script to do some basic cleanups and checks and run the docker build and run command. 
  3. db_startup_script.sh - an utility script to setup databases and setup the database configurations and data directories and to restart the services. This also runs every time you start the container. 

Make sure the docker.sh file is executable:




Step 2: In "docker.sh", check and specify version of Bahmni you want to install, what ports to bind and container name that you want to have etc. 

  1. Container name: default container914

    (I like to name the containers by the version of Bahmni I am installing. Notice the name?)

  2. Bahmni Version: change the "rpm_version" variable. 

    You can mention a specific version (like above), or the latest (like below)

  3. Ports: These are the ports that will be bound from your host to the docker container. 

  4. Inventory: Specifies what components you want installed. The inventory file controls what components of Bahmni gets installed. For example, if you want PACs (dcm4Chee) to be installed, then you should update the inventory file so that "dcm4chee" and "dcm4chee-db" have the location specified, which in this case would just be 127.0.0.1. In this example, the inventory name is set as "aws_qa03" in the docker.sh file. 

    The inventory file gets downloaded from bahmni-tw-playbooks repo. Note, these are sample inventory files. If you want to have your own inventory file, just download one of the inventory files and modify it appropriately locally, and then specify your local file to be used. To do that follow the steps below (assuming you have your local inventory as "local") 

    a) comment off the below line in "Dockerfile"

    b) And add the following line 


Step 3: Run the following command from the directory you created above ("dev_dockerFiles") 


Step 4: If all goes alright, your docker container is all set, and you can login to the container


Step 5: Check if Bahmni is running by opening a browser and typing the URL "https://localhost" or "https://localhost/bahmni/home". Also login to the container and see if the servers are running (if you get a message on the browser like 'System down for maintenance'). 


And assuming all went well, congratulations, you are all set with dockerized bahmni! 


Step 6: Ok, now that everything is up, its a good idea to commit all your changes to the container locally. To do this, follow the suggestion below

You can then stop/start the container. You can also pause, unpause container to reduce overload on your system


Troubleshooting

Like everything else, things do not go quite alright every time. Following are some of the hiccups we have faced and here are some pointers for resolutions

  1. Running the docker.sh script failed.
    1. Please check the log on the console. Try to find out what went wrong. Ask for help in community channels (slack or OpenMRS talk)
    2. Try running the script again. Sometimes internet is just flaky, and download of some packages might have failed. Try to go through the console log and see if some warning or error were logged before the eventual step of exit. 
    3. Try to delete the old docker containers and images and re-run the script. 
    4. Try removing the volume. 
    5. Read the fine manual(s) - docker, bahmni etc! Google - chances are someone already came across the same problem. 
  2. Running the docker.sh script went fine, essential openmrs and other application services are running, but databases seemed not running. Try starting the databases manually. NOTE: do these inside the container, not in your host machine.
    1. if you get messages like "Mysql is dead but subsys locked", try deleting the mysql lock file from "/var/lock/subsys/"
    2. If you get messages like "Lock file 'postmaster.pid' file already exists, try deleting pid file from '/usr/local/var/postgres'. 
    3. Check ownership of the mysql data directories. Change to 'mysql' if not

  3. If the databases are not running, try running the startup script within the container

  4. In few occasions (noticed on OSX Sierra), the mysql database is found to be corrupted post installation. To resolve this, do the following

    stop mysql  => setup innodb force recovery in my.cnf => start mysql => stop mysql > change my.cnf to comment off the innodb recovery line => start  mysql => start application services. 

  5. The database didn't get installed at all. Few have faced this on Mac and Ubuntu. To check this go to /{container_name}/mysql/ and see if there exists a database "openmrs". If not, then the database didn't get copied for some reason. To fix this, do as described below

      

Its always a good idea to save your container (using docker commit command) above once you have resolved any issues. 

Please leave a comment if you find any issues and resolutions. Better still, start a thread on OpenMRS talk channel on Bahmni, or communicate over slack or IRC. 


Developer Notes

Assuming that you, as a developer, have set up your docker instance like above and verified applications are running, you probably want to use docker as your developer environment while your primary development (writing code) happens in the host.   

Remember that you have mapped your bahmni working above following instructions at this step 1 info? Within the container, "/bahmni_host/"  is now the shared directory for your codes checked our in the host bahmni working directory. 

Prepare your development machine as described Setting up Bahmni Dev Environment


  1. Working on Bahmni Apps
    • Just like it is described in Setting up Bahmni Dev Environment#CreateLinkstoyourHostMachineFoldersforEMRUI, you want to link up your code from development machine to the running environment in Docker, only difference been the reference-able directory from docker is now "/bahmni_host/". For example, if you want "/var/www/bahmniapps" to point to your code, then create a symlink like 

  2. Working on "App Config"
    • If you want to map your working app configurations then create a symlink like 
  3. Developing OpenMRS Modules refer to Setting up Bahmni Dev Environment#DevelopingOpenMRSJavamodules
  4. Debugging Java Processes: It is same as described here, other than that the IP address is different
    1. remember you mapped ports in Step 2.4? 
  5. (Q: Did you remember to save your container with a local commit?)