Printable Installation Guide

Table of Contents How to use this guide Editing this document Saving as PDF Step 1 - Install Firefox Step 2 - Install Java Step 3 - Install Tomcat Step 4 - Install MySQL Step 5 - Deploy OpenMRS Step 6 - Configuration Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Notes Step 7 - Start Using OpenMRS

How to use this guide

Editing this document
This document is a synthesis of multiple pages in the OpenMRS wiki. As a result, it may become outdated and not contain all relevant sub-pages. Edit this page only to change the structure of the document. To edit content, edit the individual pages located elsewhere in the wiki.

Saving as PDF
To save this guide as a PDF, select "Export to PDF" in the Tools menu, located in the upper right of the wiki's display.

Step 1 - Install Firefox

Unknown macro: {scrollbar}

Windows
1. Download the latest stable release of Firefox and run installation program 2. Accept the license agreement 3. Select Standard or Custom installation to install to c:\Program Files\Mozilla Firefox

Other Operating Systems

1. See the instructions at http://support.mozilla.com/en-US/kb/Installing%20Firefox

Step 2 - Install Java Windows

1. Download the latest stable release of the Java Runtime Environment (JRE) a. Click on the "Download JRE" button b. Accept the license agreement on the download page c. Click on the link to download one of the Windows installers i. jre-[version name]-windows-i586.exe for a 32-bit Windows x86 system ii.

1.

c. ii. jre-[version name]-windows-x64.exe for a 64-bit Windows x64 system 2. Run the install program (e.g., jre-6u25-windows-i586.exe) 3. Accept the license agreement and default installation directories

Ubuntu 10.10
Note: In Ubuntu 10.10, the canonical repositories are disabled by default. Enable these by editing /etc/apt/sources.list 1. Open the Terminal by clicking on the Applications menu and going to Accessories > Terminal 2. Make a backup of the sources.list file: 3. Open the file in an editor: a. Use the arrow keys to move through the file b. Use CTRL-N to move to the next line c. Use CTRL-P to move to the previous line 4. Uncomment the following lines by deleting the "#" and space in front of each line: a. Commented lines: b. Uncommented lines: c. If you can't find the two lines in the file then add the two uncommented lines to the end of the file 5. Save the file by pressing CTRL-O (the letter O) and hitting the Enter key 6. Exit the editor by pressing CTRL-X 7. Update repositories in the Terminal: 8. Install Java: 9. 10. 11. 12. Type "Y" and the Enter key when it says on the screen "Do you wish to continue [Y/n]?" Accept the first license agreement by pressing the Tab key followed by the Enter key Accept the second license agreement by pressing the Tab key to highlight "Yes" then the Enter key Verify that Java is installed: a. You should see something like this: b. If you see OpenJDK then run the following command with two dashes before config:

Select the user/lib/jvm/java-6-sun/jre/bin/java option Use the java -version command to verify the changes

Ubuntu (prior to 10.10)

1. Open the Terminal by clicking on the Applications menu and going to Accessories > Terminal 2. Type in the following command in the Terminal 3. Accept the license agreements 4. If that doesn't work, run the following commands from the Terminal: a. For Ubuntu 9.10:

Other Operating Systems

1. Download the latest stable release of the Java Runtime Environment (JRE) 2. Run the installer (or unzip the contents, whichever is needed) 3. Accept the license agreement

Step 3 - Install Tomcat

Java must be installed before installing Apache Tomcat. There are issues with versions of Tomcat later than 6.0.29 that have yet to be resolved. Installation through a package manager is not recommended as this will likely install a later version

Windows
1. Download Tomcat 6.0.29. You can use the exe version, which installs Tomcat as a service or the zip archive. 2. If using the exe version, run the installer accepting the default settings: a. Accept the license agreement b. Accept component defaults (Tomcat, Start Menu Items, Documentation) c. Accept default destination folder: C:\Program Files\Apache Software Foundation\Tomcat 6 d. Accept HTTP/1.1 Connector Port (8080) e. Set Administrator login (admin/password) f. Accept path for the JRE (ie. C:\Program Files\Java\jre1.5.0_06) or navigate to the actual path and select g. Select "Install Tomcat" 3. Open the Tomcat users file (e.g. C:\Program Files\Apache Software Foundation\Tomcat 6.0\conf\tomcat-users.xml) in a text editor. Create a new user called admin with the roles admin, manager and manager-gui. This file should be protected so you will need to open it as Administrator (right-click on your text editor and select "Run as administrator") 4. (Optional) If you've installed Tomcat as a service, you can configure it to start automatically when the computer boots: a. Start > Settings > Control Panel > Administrative Tools > Services b. Right Click "Apache Tomcat" > Properties > Set "Startup Type" to Automatic

Other operating systems

1. Download the zip archive of Tomcat 6.0.29 2. Unpack the zip file to a suitable location such as /opt on Linux or /Library on Mac OSX 3. Open the Tomcat users file (e.g. /opt/tomcat/conf/tomcat-users.xml) in a text editor. Create a new user called admin with the roles admin, manager and manager-gui. This file should be protected so you will need to open it as root (e.g. sudo nano /opt/tomcat/conf/tomcat-users.xml)

As a Debian package
This is not recommended as it may install a version of Tomcat which is not compatible with OpenMRS. 1. Run the following command from a terminal 2. Open the Tomcat users file (e.g. /etc/tomcat/tomcat-users.xml) in a text editor. Create a new user called admin with the roles admin, manager and manager-gui. This file should be protected so you will need to open it as root (e.g. sudo nano /etc/tomcat/tomcat-users.xml) 3. Turn off tomcat security flag in /etc/init.d/tomcat6 file: Find "TOMCAT6_SECURITY=yes" and change it to "TOMCAT6_SECURITY=no" 4. Create OpenMRS application data directory and make it writable by Tomcat: (so that the runtime properties file can be written by the webapp during initial startup)

Jetty as an alternative to Tomcat

This is meant to run in a Linux environment. 1. Download the Jetty 7.4.5 tar.gz from here. Don't download 7.5.4; it may not recognize the jdk that you have installed. 2. Unpack the tar file to your preferred directory (I usually use /usr/share/jetty) 3. Now to make it start when you start the system and make Jetty a service 4. Edit /etc/init.d/jetty to include the following two lines after the comments so Jetty knows where your Java and Jetty directories are. 5.

5. Jetty is now officially installed and can be run as a service. Now you can run Jetty by using the following command. First put the openmrs.war in to /usr/share/jetty/webapps/ so Jetty will know to run the war.

Step 4 - Install MySQL

Windows 1. Download the latest stable (recommended, generally available) release of MySQL 2. Extract with an unzip tool such as WinZip 3. Run the MySQL install program (setup.exe) and then either: a. Choose Custom Setup b. Change the installation directory to C:\MySQL5 and the data directory to c:\MySQL5\data\. We recommend installing into a directory without spaces, e.g., c:\MySQL5* or *c:\MySQL5\data. The default directory usually includes spaces, which seems to cause problems with MySQL. 4. Accept the license agreement 5. Accept to Configure Instance a. Select "Detailed Configuration" b. Select "Developer Machine" c. Select "Multifunctional Database" d. InnoDB Tablespace Settings, Use the default (c: and Installation Path). e. Select "DSS/OLAP" f. Enable TCP/IP Networking (Port 3306), check "Add firewall exception..." and leave "Enable Strict Mode" checked. g. Default Character Set, select "Best support for Multilingualism" (utf8) h. Check "Installed as Windows Service" and leave "Launch the MySQL Server automatically" checked. i. Root password (password) (Note: Do NOT forget this root password for MySQL! You will need it later.) j. Execute the configuration. The installer should step through the process and give you green check marks at each stage 6. If you run into problems, check the Installation Troubleshooting page or the Troubleshooting MySQL page 7. Enable the MySQL port in Windows Firewall a. Open Windows Firewall (Start ? Settings ? Control Panel ? Windows Firewall) b. Under the "Exceptions" tab, click the "Add Port" button c. Name: MySQL d. Port number: 3306 e. Optional: For added security, click the "Change scope" button and limit to "My network (subnet) only". This will prevent computers outside of your local area network from being able to access your database directly.

Other Operating Systems

1. Install the MySQL server package: sudo apt-get install mysql-server 2. Enter a root password

Step 5 - Deploy OpenMRS

Unknown macro: {scrollbar} 1. (In Windows) Ensure that Tomcat is started by checking to see if icon in the tray is green 2. Download the latest stable release of OpenMRS 3. Navigate to http://localhost:8080/manager/html and enter your Tomcat administrator credentials (username and password chosen when installing Tomcat) 4. In the Tomcat Web Application Manager, enter the location of the downloaded openmrs.war file to deploy a. The deployment could take some time while the file is copied to the folder C:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps and decompressed b. Note that the OpenMRS.war file is most easily downloaded with Mozilla Firefox. Internet Explorer tries to open the file as a Zip file. 5. At the end of this process, the web page will refresh and /openmrs should be displayed under Applications. Apache Tomcat should also start the application (Running = True; and in Commands, Stop is underlined)

Step 6 - Configuration
Unable to render {include} Couldn't find a page to include called: Step 6 - Configuring OpenMRS

Step 7 - Start Using OpenMRS

Unknown macro: {scrollbar} 1. After you have finished configuring OpenMRS, reload the application in Tomcat Manager. 2. Open http://localhost:8080/openmrs. You will see a login page. a. You will need to log in initially using the username and password you specified in Step 6 - Configuring OpenMRS, substep 4. If

2. a. you did not specify a username and password, try the default username admin and password test (both are in lowercase). b. Alternatively, while Tomcat is running you can start OpenMRS by entering http://localhost:8080/openmrs/login.htm (assuming 8080 is your port number for Tomcat; insert the appropriate port number if it is not 8080).