Linux guide

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 Linux (on varied distributions) 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.

Contents

[edit]

STEP 1- Pre-Requisites for Installing OpenMRS

Download and install the latest stable release of the following software

  1. Java JDK (Downloads from Sun)
  2. MySQL 5.x (Downloads from MySQL.org)
  3. Ant (ant.apache.org)
  4. Tomcat (Tomcat site) (Note: there seems to be problems, at least with Ubuntu, with the packaged tomcat server. See this link. ) So, the best bet is to install Tomcat from the Tomcat site:
    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. 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 (eclipse.org) The version on the Eclipse site is more up to date, and is the version currently in use by OpenMRS devs.
  7. One (or more) Subversion client:
    1. Subversion OR Subclipse (if you're working within Eclipse only)

You can install packages from these sites (or install from source) if you want the most up-to-date versions. However, these are all likely available as packages for your distribution. For Ubuntu, you would use commands such as: 

  sudo apt-get install sun-java5-jdk (for Ubuntu and Debian)
  sudo apt-get install mysql-server

To install Subclipse from Eclipse, see the Developer How-To Use Eclipse Guide.

If you install anything from source, make sure to include any executables (like eclipse and mysql) in your PATH.

[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. 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 (note, if you use Eclipse and you used defaults, it will likely be in ~/workspace/openmrs/metadata/model/)
  2. Launch mysql server 
    sudo mysqld_safe --user=mysql &
  3. Launch mysql console using mysql prompt: 
    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_[version]-mysql.sql (generates the data model)

    mysql> source openmrs_[version]-data-mysql.sql (populates tables)

    mysql> source openmrs_[version]-patient-data-mysql.sql (fills tables with fake patient data)

    mysql> source openmrs_[version]-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)






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