Step-by-Step Installation for Developers on OS X

This is a work in progress. The goal of this document is to provide clear and simple instructions for getting OpenMRS up and running on OS X for developers. Please use the discussion page if you feel anything needs fixing or clarification. These instructions should be as easy as possible to follow successfully.

An updated form of this guide can be found at Installation for Developers on OS X

Contents

[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. MySQL 5.x
    1. Download and install pkg file.
    2. Optionally, add mysql to your path: 
      alias mysql=/usr/local/mysql/bin/mysql
      or 
      PATH=$PATH:/usr/local/mysql/bin
    3. You may also install MySQL.prefPane to start and stop the server
  3. Ant
    1. Extract binary installation to /usr/local/apache-ant-x.x.x/
    2. Optionally, create a symlink for this ant installation 
      ln -s /usr/local/apache-ant-x.x.x /usr/local/ant
    3. Prepend Ant's bin directory to $PATH 
      PATH=/path/to/ant_path/bin:$PATH
    4. Set $ANT_HOME to the Ant installation directory 
      export ANT_HOME=/path/to/ant_path
    5. You should also set $JAVA_HOME to the path of the JDK. The following should work for OS X: 
      export JAVA_HOME=/Library/Java/Home
  4. Tomcat 5.5+
    1. Extract binary installation to /usr/local/apache-tomcat-x.x.x/
    2. Optionally, create a symlink for this tomcat installation 
      ln -s /usr/local/apache-tomcat-x.x.x /usr/local/tomcat
    3. Set $CATALINA_HOME to tomcat_path 
      export CATALINA_HOME=/path/to/tomcat_path
    4. Add the following line to $CATALINA_HOME/conf/tomcat-users.xml between <tomcat-users></tomcat-users> 
      <user username="test" password="test" roles="admin,manager,tomcat"/>
    5. Start Tomcat: 
      $CATALINA_HOME/bin/startup.sh
    6. 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.
    7. Test that Tomcat is working: Your Local Tomcat Instance
  5. lcab and cabextract
    1. Download and extract the latest source code packages.
    2. Build and install each from the command line. 
      ./configure && sudo make install
  6. Eclipse
  7. One (or more) Subversion client:
    1. Subversion OR Subclipse (if you're working within Eclipse only)
[edit]

STEP 2- Retrieve a Copy of the Source Code

  • With Subversion installed:
    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
  • With Subclipse installed (in Eclipse):
    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, navigate to openmrs/trunk
    6. Right-click 'build.xml' file
    7. Select Run As-->Ant Build...
    8. Choose 'install' for the first install and 'update' for subsequent installs.
[edit]

STEP 3- Create the Database

  1. Change to the OPENMRS/metadata/model/ directory
  2. Launch mysql server (or with the MySQL.prefpane if installed earlier) 
    sudo /usr/local/mysql/bin/mysqld_safe --user=mysql &
  3. Launch mysql console using mysql prompt: 
    /usr/local/mysql/bin/mysql -u root
  4. Initialize the OpenMRS databases with mysql in the following order (from the mysql prompt): 
    mysql> source openmrs_createdb-mysql.sql (generates the OpenMRS database)

    mysql> source openmrs_1.1.0-mysql.sql (generates the data model)

    mysql> source openmrs_1.1.0-data-mysql.sql (populates tables)

    mysql> source openmrs_1.1.0-patient-data-mysql.sql (fills tables with fake patient data)

    mysql> source openmrs_1.1.0-to-latest-mysqldiff.sql

    mysql> quit

    

  5.  Make sure you can log in to mysql with username 'test' and password 'test'.

    /usr/local/mysql/bin/mysql -u test -ptest

    

    1.  If this gives you the mysql> prompt, you are fine.  If you cannot login as test, login as root and execute the following code, and you should be able to login as test:

      /usr/local/mysql/bin/mysql -u root

      mysql> drop user test;

      mysql> create user 'test'@'localhost' identified by 'test';

      mysql> grant all on openmrs.* to test;

      mysql> quit

      

    



[edit]
STEP 4- Set up your Local Configuration


(optional) 



  1.  It is possible to use usernames/passwords that are not the default (insecure) ones.  See Overriding OpenMRS Default Properties.

     NOTE: Don't forget to grant privileges for this MySQL account to the OpenMRS data model!

    



[edit]
STEP 5- Install the WAR File


  1.  Assuming Ant is in your path, run the Ant task ant install in the top level directory of your copy of the code (the directory containing build.xml).  Subsequent re-installs can be done using ant update.

  2. View your installation at http://localhost:${tomcat.port}/${webapp.name}/ (Default is http://localhost:8080/openmrs)



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/Step-by-Step_Installation_for_Developers_on_OS_X"