Vagrant Development Environment (Core Development)

Link: https://github.com/openmrs/openmrs-core

Sets up a headless development Virtual Machine on your computer using Vagrant

Vagrant Overview

• "vagrant up" to read the configuration Vagrantfile which tells how to build the virtual machine
  • Downloads a base virtual image (called a box ) to create the development environment from (boxes stored in locally in user directory e.g. C:\Users\Tim\.vagrant.d\boxes / ~.vagrant.d\boxes)
  • Once virtual machine is booted it will perform any configurations set in the Vagrantfile
    • e.g. install tomcat and openmrs, set up networking (currently done via puppe)
• "vagrant destroy" will kill the entire virtual machine. all data deleted
• "vagrant halt" to shutdown the virtual machine. data still persists
• "vagrant ssh" (or ssh to 127.0.0.1:2222)

Vagrant Setup

• 1. Ensure your computer is plugged in and connected to the Internet :)

  2. Download and Install the latest VirtualBox: https://www.virtualbox.org/wiki/Downloads

  3. Download and Install the latest Vagrant: http://www.vagrantup.com/

  4. Go and login to Github: https://github.com (If you do not have a Github account, please sign up for Github to login)

  5. Once you have logged in to Github, go to "Set up Git" in your Github User Interface

     • Set up Git (image) http://i.imgur.com/9xFDKnb.png

  6. From there, Download and Install Git (or go to http://git-scm.com/downloads)

  7. Go to https://github.com/openmrs/openmrs-core

  8. Clone this repository at the command line (or at Git Shell if you cannot use Git commands in the command line. Go to terminal if using a Mac) git clone https://github.com/openmrs/openmrs-core.git OR go to https://github.com, login to your account, go to that repository and click the "Clone in Desktop" button on the right hand side of the page

  9. Open the command line and head to the openmrs-core directory (this can be found in the Github directory)

  10. Type vagrant up

      • vagrant up (image): http://i.imgur.com/F6xM8gI.png
      • vagrant up finished (image): http://i.imgur.com/scymAAR.png

  11. Allow time (+/- 20 minutes) for the base image and packages to download and install. It may look like it has hung or stopped working at times, but that's just part of the process - be patient!

  12. You might see errors on the last step, but that's OK. I plan on fixing this though! http://i.imgur.com/xwsi5Vk.png

  13. Connect to the box:

      • Linux or OS X type this to connect to the box: vagrant ssh

      • Windows, you will need an ssh client like Putty: http://www.putty.org/

        • Host: 127.0.0.1
        • Port: 2222
        • User: vagrant
        • Password: vagrant

      • Additional info available here: http://docs-v1.vagrantup.com/v1/docs/getting-started/ssh.html

      • Putty (image): http://i.imgur.com/XEk95VE.png
      • Putty (image 2) https://openmrsau.imgur.com/all/

  14. Restart the avahi-daemon service: sudo service avahi-daemon restart

      • Restart (image): http://i.imgur.com/oKJGmrX.png

  15. Go to the vagrant directory (cd /vagrant)

  16. run "mvn clean install"
  17. Go to the webapp directory (cd /vagrant/webapp)
  18. run "mvn jetty:run"
  19. Go to your host machine and open your web browser to http://192.168.33.10:8080/openmrs or http://openmrs-dev.local:8080/openmrs

  20. In the installation wizard, for the question "Which type of installation do you want?", choose "Simple" and press the right arrow button

      • Installation steps (image): http://i.imgur.com/UAENpg4.png

  21. Enter the MySQL password: OpenMRS (Make note that the default admin credentials for this site is: admin/Admin123)

  22. In the installation wizard, for the question "Do you want to also add demo data to your database - openmrs?", choose "Yes" and press the right arrow button

      Installation steps (image): http://i.imgur.com/9ySYkFO.png

  23. Review the information and press the right arrow button (It will now install the OpenMRS core)

      • Installation review (image): http://i.imgur.com/jZUbLgN.png
      • Installation of OpenMRS core (image): http://i.imgur.com/DEAthnA.png
  24. Go to your host machine and open to your web browser to http://192.168.33.10:8080/openmrs or http://openmrs-dev.local:8080/openmrs and you should be directed to the webapp main page

Vagrant Filepaths

• User downloaded files like boxes
  • Windows: C:\Users\Tim\.vagrant.d\
  • *nix: ~/.vagrant.d
• Virtual Machines created
  • C:\Users\Tim\VirtualBox VMs\
    • openmrs-dev
    • precise32 (based on box downloaded specified in Vagrantfile)
• Vagrant system/executable files themselves
  
  • Windows: C:\HashiCorp\Vagrant

Credentials to Vagrant VM

User: vagrant

Password: vagrant

Issues Encountered Setting up Vagrant

• Corrupt / Incomplete box download (can't remember the error)
  • Deleted download box file in ~/.vagrant.d/boxes
• Windows: vagrant not recognized in command line
  • Add to PATH environment variables or just run the following "PATH=%PATH%;C:\HashiCorp\Vagrant\bin" (alter based on your install location)
• "vagrant up" complains about not supporting VirtualBox and does not start
  • Update Vagrant to latest version. 
    • Older versions of Vagrant may not work well / may not support newer version of VirtualBox. 
    • Sample error message below with the error in bold. 
    • Other messages are just notices and typically still allow the virtual machine to run
    • Updating Vagrant to the latest version solved it
      
      

      There were warnings and/or errors while loading your Vagrantfile
      for the machine 'default'.

       

      Your Vagrantfile was written for an earlier version of Vagrant,
      and while Vagrant does the best it can to remain backwards
      compatible, there are some cases where things have changed
      significantly enough to warrant a message. These messages are
      shown below.

       

      Warnings:
      * `config.vm.customize` calls are VirtualBox-specific. If you're
      using any other provider, you'll have to use config.vm.provider in a
      v2 configuration block.
      Vagrant has detected that you have a version of VirtualBox installed
      that is not supported. Please install one of the supported versions
      listed below to use Vagrant:

       

      4.0, 4.1, 4.2, 4.3

      
       
• Puppet never ran on the VM machine
  
  • try "vagrant reload --provision"
    otherwise 
  • try a complete reload with "vagrant destroy" then "vagrant up"
• openmrs-dev.local:8080 not accessible on host machine
  
  • check IP of virtual machine (ifconfig)
    • access using the IP found
        or
    • add IP to the host file (C:\Windows\System32\drivers\etc\hosts or /etc/hosts)

      • 192.168.33.10 openmrs-dev.local