Installation for Developers on OS X

This page was written 2/14/2009 for installation of OpenMRS for development on OS X. This guide recommends and will focus on development with Eclipse and the Subclipse plugin for SVN.

NOTE: Although the compiler for eclipse recommended below is 1.5.xx, there have been major issues getting Mac OS X leopard working while running Java 1.5. 1.6 is required for the website logic. Unfortunately, 1.6 is 64 bit, so snow leopard is fine, but leopard needs a work-around to get Java 1.6 running. One such patch is the soylatte project. But I tried soylatte and still ran into problems (although those could be different issues). Anyways, be advised that windows and snow leopard are more likely to work right off the bat.

[edit]

STEP 1- Pre-Requisites for Installing OpenMRS

Download and install the latest stable release of the following software

  1. Java JDK (This gets installed automatically with XCode)
  2. Eclipse
  3. One (or more) Subversion client:
    1. Subclipse/Subversive If you're working within Eclipse only (quickest setup)
      • Note: The setup is done through Eclipse, but the instructions are on the subclipse page
    2. Subversion
      • Note: If later you receive a cryptic 'Unable to load default SVN client' error when creating an SVN project, you must update your SVN binaries (download).
  4. MySQL 5.x
    1. Download and install pkg file. CHECK THE OS AND 32/64 BIT for compatibility
    2. If available, also install MySQL.prefPane to start and stop the server from the System Preferences (easier than command line)
  5. Ant This is included with the most recent distributions of Eclipse
    1. Extract binary installation to /usr/local/apache-ant-x.x.x/
  6. lcab--3/2010 it appears this software is no longer obtainable (Only needed if you're going to be using the FormEntry Module)
    1. Download and extract the latest source code packages.
    2. Build and install each from the command line by using cd to get into its directory, then run 
    ./configure
    sudo make install
  7. cabextract--3/2010 it appears this software is no longer obtainable (Only needed if you're going to be using the FormEntry Module)
    1. Download and extract the latest source code packages.
    2. Build and install each from the command line by using cd to get into its directory, then run 
    ./configure
    sudo make install
  8. Tomcat 6+
    1. Get the binary, core distribution and extract it. Move it to /usr/local/apache-tomcat-x.x.x/
    2. Set $CATALINA_HOME environment variable 
      export CATALINA_HOME=<path to tomcat>
      to the path to tomcat where, per the above line, <path to tomcat> = /usr/local/apache-tomcat-x.x.x/
    3. Increase the memory available to tomcat 
      export CATALINA_OPTS='-Xmx512m -Xms256m -XX:PermSize=256m -XX:MaxPermSize=512m -XX:NewSize=128m'
    4. Add the following 4 line(s) to $CATALINA_HOME/conf/tomcat-users.xml between <tomcat-users> and </tomcat-users>
    <role rolename="tomcat"/>
    <role rolename="manager"/>
    <role rolename="admin"/>
    <user username="test" password="test" roles="admin,manager,tomcat"/>

Once those 4 lines have been added, the tomcat-users.xml file should look like this: 

 <tomcat-users>
      <role rolename="tomcat"/> 
      <role rolename="manager"/> 
      <role rolename="admin"/> 
      <user username="test" password="test" roles="admin,manager,tomcat"/>
 </tomcat-users>

Start Tomcat:

NOTE: You may be able to just start Tomcat out of eclipse, by running tomcat-start in the Ant view in eclipse. To do this, right click the build.xml and select Open With->Ant Editor. Expanding OpenMRS-trunk gives a list of ant scripts you can run by right clicking and selecting Run As->Ant Build 


$CATALINA_HOME/bin/startup.sh
  • or for more debugging printed to the console 
$CATALINA_HOME/bin/catalina.sh run
  • If you get a "permission denied" error when starting, then type this in the Terminal : "chmod a+x *.sh" without the quotes. It should permanently enable the permission to run .sh files as executable.
  • To stop it, you can either run the ant script tomcat-stop, or 
$CATALINA_HOME/bin/shutdown.sh

Test that Tomcat is working: http://localhost:8080/ and check that it says "If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!"

[edit]

STEP 2- Retrieve a Copy of the Source Code

With Subclipse installed (in Eclipse):

  • (Relic?) Note- prior to starting, make sure that the workspace directory has a normal path. By default, Eclipse may point to a directory within eclipse.app, and most OSX file browsers will not be able to access this.
  1. File-->New-->Project...-->SVN-->Checkout project from SVN
  2. Use Repository - http://svn.openmrs.org/openmrs/
  3. Browse in new tree to /openmrs/trunk
  4. Go through various prompts with Next>
  5. In Package Explorer, in the Java view (chosen in upper right tab), navigate to openmrs/trunk
  6. Modify the properties.xml file to use the Mac-specific file for the tomcat/ catalina home directories. Replace xx so that it matches your distribution 
     <property name="tomcat.home" value="/usr/local/apache-tomcat-6.0.xx"/>
    <property name="catalina.home" value="/usr/local/apache-tomcat-6.0.xx"/>
  7. Make the file OPENMRS-build.properties
    1. Open a text editor (TextEdit, for example)
    2. Copy-and-paste Build Properties section from Overriding OpenMRS Default Properties into it
    3. Save the file to 
      ~/.OpenMRS/OPENMRS-build.properties
      (you'll probably have to make the .OpenMRS folder)
    4. Modify the Build Properties to match the location for your installation of Tomcat. 
      tomcat.home=/usr/local/apache-tomcat-6.0.xx
      for example
      NOTE: Make sure the file does not save with a .txt file extension behind the scenes (Turn on 'show extension' and remove it).
  8. Right-click 'build.xml' file
  9. Select Run As-->1. Ant Build 
With Subversion installed:  (ignore this block of 4 instructions if you have subversion)
  1. Create a new directory for the code. Our example will call it OPENMRS.
  2. From the OPENMRS directory, run 
     /usr/local/bin/svn checkout http://svn.openmrs.org/openmrs/trunk
  3. or 
     svn checkout http://svn.openmrs.org/openmrs/trunk
  4. From the OPENMRS/trunk directory, run 
    $ANT_HOME/bin/ant install
    Future compilations can run using 
    $ANT_HOME/bin/ant update
[edit]

STEP 3- Create the Database

  1. Launch mysql server either with the MySQL.prefpane if installed earlier, or the command 
    sudo /usr/local/mysql/bin/mysqld_safe --user=mysql &
  2. Open Your Local Tomcat Instance (localhost:8080)
  3. From the Administration Pane in the top left, click "Tomcat Manager" (or go to localhost:8080/manager/html)
  4. This will now ask you for a user name and password, if you altered tomcat-users.xml per the above the username should be "test" and the password should be "test" without the quotes.
    • If this does not seem to be working, check that the contents of your tomcat-users.xml match that above
  5. You should now see the "Tomcat Web Application Manager"
  6. Scroll down to the "War file to deploy" area and select browse
  7. Locate the War file that you created earlier, this should be .../openmrs-trunk/dist/openmrs.war or similar ('...' would be your eclipse workspace)
  8. Click deploy
  9. If deployment was successful, /openmrs should appear under the Applications pane in the Tomcat Manager, click it
  10. This should take you to the openmrs install wizard (follow the link to see the screenshots with instructions)
  • During development, Ant update can be used to build changes into your local OpenMRS install.
  • To do this in Eclipse, while viewing the openmrs-trunk in the project explorer, in the Outline pane look for "update". Right Click "update" and select Run As-> 1 Ant Build

Note: Repeatedly re-deploying can cause an OutOfMemoryError where Tomcat runs out of PermGen Space! See this for information on how to remedy this problem.

Retrieved from "http://openmrs.org/wiki/Installation_for_Developers_on_OS_X"