Step-by-Step Installation for Developers

This guide is focused on Windows users. A guide for OS X users can be found at Step-by-Step_Installation_for_Developers_on_OS_X (this should also work for Linux users as well, but a Linux guide is in the works).

Contents 1 STEP 1 - Prerequisites for Installing OpenMRS 2 STEP 2 - Retrieve a Copy of the Source Code 3 STEP 3 - Create the Database 4 STEP 4 - Set up your Local Configuration (optional) 4.1 Create OpenMRS database user 4.2 OpenMRS-build.properties 4.3 Create OpenMRS-runtime.properties 5 STEP 5 - Deploy OpenMRS 5.1 Eclipse (in Windows, Linux, Unix, Mac) 5.2 Command Line (Windows XP) 5.3 Command Line (Unix / Linux)

STEP 1 - Prerequisites for Installing OpenMRS

1. Download and install the latest stable release of the following software
   • Java >= v1.5 aka v5.0 (implementers can use the JRE, developers need the JDK)
   • MySQL 5.x
   • Ant
   • Tomcat
   • Eclipse IDE for Java EE Developers
     • Install the OpenMRS customizations at here
   • One (or more) Subversion client:
     • Subversion OR
     • TortoiseSVN (if you're working within Windows) OR Subclipse (if you're working within Eclipse only)
     • NOTE- You may use both TortoiseSVN and Subclipse, but only one is necessary.
     • Growl + growlnotify (in the Growl Extras folder) - for Macs

STEP 2 - Retrieve a Copy of the Source Code

1. With Subversion installed:
   1. Create a new directory for the code. Our example will call it OPENMRS.
   2. At a command line prompt in the OPENMRS directory, run %SVN_HOME%/bin/svn checkout http://svn.openmrs.org/openmrs/trunk
2. With TortoiseSVN installed:
   1. Right-click within explorer and select SVN Checkout...
   2. Enter URL as http://svn.openmrs.org/openmrs/trunk, specify a new directory for your working copy, then click OK
3. With Subclipse installed (in eclipse):
   1. File-->New-->Project...-->SVN-->Checkout project from SVN
   2. Use Repository - http://svn.openmrs.org/
   3. Browse in new tree to /openmrs/trunk
   4. Go through various prompts with Next>
4. At the command line prompt in the OPENMRS directory, run %ANT_HOME%/bin/ant install
5. Future compilations can run %ANT_HOME%/bin/ant -k clean remove install or %ANT_HOME%/bin/ant update

STEP 3 - Create the Database

1. Within your working copy, find the SQL scripts within the /metadata/model/ folder
2. Launch mysql and run the script openmrs_createdb-mysql.sql to drop/generate the OpenMRS database. Be sure to use the fully qualified path such as: source C:\Documents and Settings\Jim\workspace\OpenMRS\metadata\model\openmrs_1.2.0-mysql.sql

   "c:\Program Files\MySQL\MySQL Server 5.0\bin\mysql.exe" -u root -pmyrootpassword

   mysql> source openmrs_createdb-mysql.sql

3. Run these scripts in order in the same way as the first script at the mysql prompt: Note: you may have to select the database you're using before any of these calls by typing 'use openmrs;'
   1. openmrs_1.2.0-mysql.sql -- This generates the data model.
   2. openmrs_1.2.0-data-mysql.sql -- This populates tables.
   3. openmrs_1.2.0-patient-data-mysql.sql -- This is scrambled data and names. The data is real, however, all personal information is completely fabricated.
   4. openmrs_1.2.0-to-latest-mysqldiff.sql -- This should be done last

STEP 4 - Set up your Local Configuration (optional)

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

Create OpenMRS database user

1. Log into mysql command line client as root (needs more explicit instructions)
2. Create new 'openmrs' user with password 'openmrs'

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

    mysql> set password for openmrs@localhost=PASSWORD('openmrs'); 

3. Grant all privileges (select insert drop create...) to 'openmrs' user to openmrs schema

    mysql> grant ALL on openmrs.* to openmrs; 

NOTE: Using 'openmrs' for the username and password is insecure, so please change these for your configuration.

NOTE: Write down the the username and password!

OpenMRS-build.properties

1. Open a text editor (i.e. Notepad - click Start > Programs > Accessories > Notepad)
2. Copy-and-paste Build Properties section from Overriding OpenMRS Default Properties into Notepad
3. Save file to
4. %USER_HOME%\Application Data\OpenMRS\OpenMRS-build.properties (for windows) or ~/.OpenMRS/OpenMRS-build.properties (for unix)
5. Modify the Build Properties to match the location for your installation of Tomcat.

   for windows

   tomcat.home=C:/Program Files/Apache Software Foundation/Tomcat 6.0/

   for unix

   tomcat.home=/usr/local/apache-tomcat-6.0.16

6. If you are using unix, change your properties.xml file so that:

   <property name="tomcat.home" value="/usr/local/apache-tomcat-6.0.16"/>

   <property name="catalina.home" value="/usr/local/apache-tomcat-6.0.16"/>

Create OpenMRS-runtime.properties

1. Open a text editor (i.e. Notepad)
2. Copy-and-paste Runtime Properties section from Overriding OpenMRS Default Properties into Notepad
3. Save file to %USER_HOME%\Application Data\OpenMRS\OpenMRS-runtime.properties (for windows) or ~/.OpenMRS/OpenMRS-runtime.properties (for unix)
4. Modify the runtime properties for the OpenMRS database to match the database user you created above.

   connection.username=openmrs

   connection.password=openmrs

5. If you are using Unix, change your build.xml file so that:

   <!-- Environment properties -->

   <property environment="env"/>

   <property name="env.COMPUTERNAME" value="${env.HOSTNAME}"/>

   <property name="env.OPENMRS_RUNTIME_PROPERTIES_FILE" value="${user.home}/.OpenMRS/OPENMRS-runtime.properties" />

NOTE: Ignore the customization properties unless you plan to customize the look-and-feel for your OpenMRS implementation

NOTE: Make sure the files do not save as .txt files. This is bad.

STEP 5 - Deploy OpenMRS

Assumptions and Dependencies (needs work):

• Eclipse is installed in your machine AND
• OpenMRS source code has been downloaded using TortoiseSVN and imported into Eclipe (include link to instructions) OR
• OpenMRS source code has been downloaded using subclipse (include link to instructions)
• Ensure that Tomcat is running
• Once you are up and running, the default OpenMRS user/password is admin/test

Eclipse (in Windows, Linux, Unix, Mac)

1. Run Eclipse.exe
2. In the project explorer, right click on your OpenMRS project folder root and select "properties", left click on "Java Compiler" and ensure that the Java Compiler is set to Compiler compliance level 5.0
3. Click Window > Show View > Ant
4. Drag and Drop build.xml from the 'openmrs' project into the Ant view
5. In the Ant view (left pane), expand the 'openmrs' build file
6. Double click on the install ant task (this may take a few minutes)
7. Make sure your tomcat user has the roles manager,admin,tomcat
   • NOTE: Subsequent re-installs can be done using the update Ant task.
8. View your installation at http://localhost:${tomcat.port}/${webapp.name}/ (Default is http://localhost:8080/openmrs)
9. For support on Windows XP/Vista/Eclipse integration, contact jim@manico.net

Command Line (Windows XP)

1. Open a Windows command line prompt
   1. Click Start Menu > Run
   2. Type 'cmd' at the Open prompt
   3. Press Ok
2. Change directories to the openmrs project directory.
3. Type 'ant install'
   • Assumes that Ant has been added to your PATH (provide link to instructions)

Command Line (Unix / Linux)

1. Log into server
2. Open a bash shell