Step-by-Step Installation for Developers (for v1.0.0 to v1.4.0)

This guide is focused on Windows users. OS X users should read OS X Guide. Linux users should see the Linux guide or Linux server guide or Ubuntu 8 Guide. Finally, if you want to use a VM, there is QEMU or the OpenMRS_Appliance.

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 >= at least v1.5 aka v5.0 (implementers can use the JRE, developers need the JDK)
   • MySQL 5.x
   • Ant >= latest stable release. included with eclipse
   • Tomcat >= at least v5.5 or v6.x
   • Eclipse IDE for Java EE Developers >= latest stable release
   • One (or more) Subversion client:
     • Subversion OR
     • TortoiseSVN (if you're working within Windows) OR Subclipse (for working within Eclipse)
     • 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>

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 1.3.0-createdb-from-scratch-with-demo-data.sql to drop/generate the OpenMRS database. This particular file will create a complete database (schema, core data and demo data). Other scripts are available in the same folder that will either deploy the schema only or the schema with the core data (but not the demo data). Be sure to use the fully qualified path such as: source C:\Documents and Settings\Jim\workspace\OpenMRS\metadata\model\1.3.0-createdb-from-scratch-with-demo-data.sql

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

   mysql> source 1.3.0-createdb-from-scratch-with-demo-data.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. update-to-latest-db.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) or %USER_HOME%\AppData\Roaming\OpenMRS\OpenMRS-build.properties (for Windows Vista)
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) or %USER_HOME%\AppData\Roaming\OpenMRS\OpenMRS-runtime.properties (for Windows Vista)
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)
   • NOTE: Subsequent re-installs can be done using the update Ant task.
7. Make sure your tomcat user has the roles manager,admin,tomcat
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)
   • Future compilations can run %ANT_HOME%/bin/ant -k clean remove install or %ANT_HOME%/bin/ant update

Command Line (Unix / Linux)

1. Log into server
2. Open a bash shell
3. Change directories to the openmrs project directory.
4. Type 'ant install'
   • Future compilations can run %ANT_HOME%/bin/ant -k clean remove install or %ANT_HOME%/bin/ant update