Overview

As of OpenMRS 1.5, there is an auto-install process that makes installation easier than it was in earlier versions.

Steps Involved

1. Install Firefox
2. Install Java 5+ runtime environment
3. Install Tomcat 5.5+
4. Install MySQL 5+
5. Deploy OpenMRS
6. Go to http://localhost:8080/openmrs and follow the installation steps (note: if you are not installing on your computer, then use the domain of your server instead of localhost, port 8080 is the standard Tomcat port)

* Note: Java must be installed before Apache Tomcat

Minimum Requirements

1 GHz processor or better, 256 MB of memory or more, 40 GB hard drive or larger. You can set up the server on a laptop for demonstration or testing purposes. For production usage, we recommend one or two processors 1.5+ GHz, 2 GB of memory, and 150+ GB of disk space with RAID and appropriate backup facilities.

Example Installation Presentations

• OpenMRS Installation
  • MySQL and Firefox ( Google Doc link | Direct to Presentation )
  • Tomcat and OpenMRS Install (Based on OpenMRS v1.2, links may be out of date) Google Doc link | Direct to Presentation )

Install Firefox

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

Install Java

1. Download the latest stable release of the Java Runtime Environment (JRE)
2. Run the install program (e.g., jre-1_5_0_12-windows-i586-p.exe)
3. Accept the license agreement and default installation directories

Install Tomcat

1. Download latest stable release of Tomcat — e.g., [1] and execute file
2. Accept the license agreement
3. Accept Component defaults (Tomcat, Start Menu Items, Documentation)
4. Accept default destination folder: C:\Program Files\Apache Software Foundation\Tomcat 5.5
5. Accept HTTP/1.1 Connector Port (8080)
6. Set Administrator login (admin/password)
7. Accept path for the JRE (C:\Program Files\Java\jre1.5.0_12) or navigate to the actual path and select
8. Select "Install Tomcat"
9. Open the Tomcat users file (c:\Program Files\Apache Software Foundation\Tomcat 5.5\conf\tomcat-users.xml) in a text editor and add the roles admin and manager for the user "tomcat"

   <user name="tomcat" password="tomcat" roles="tomcat,admin,manager"/>

10. (Ubuntu Only) Turn off tomcat security flag in "/etc/init.d/tomcat6" file:

    Use the Java security manager? (yes/no)

    TOMCAT6_SECURITY=no

11. (Ubuntu Only) Fix application data directory

    sudo mkdir /usr/share/tomcat6/.OpenMRS

    sudo chown -R tomcat6:root /usr/share/tomcat6/.OpenMRS

12. Optional (Windows) Set Tomcat to start automatically
    1. Start → Settings → Control Panel → Administrative Tools → Services
    2. Right Click "Apache Tomcat" → Properties → Set "Startup Type" to Automatic

Install MySQL

1. Download the latest stable (recommended, generally available) release of MySQL — e.g., for "Windows (x86) ZIP/Setup.EXE" → mysql-5.0.41-win32.zip
2. Extract with Winzip
3. Run the MySQL install program (setup.exe) and run Custom Setup. Accept all defaults except the installation directory and the data directory, recommend installing into a directory without spaces (eg. c:\MySQL5\, 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 → Select `Detailed Configuration’ → Developer Machine → Multifunctional Database → InnoDB Settings (c: and Installation Path) → DSS/OLAP → Enable TCP/IP Networking (Port 3306) → Select "Manual Selected Default Character Set / Collation" and set the character set to utf8 → Check "Installed as Windows Service" → Root password (password) (note: do NOT forget this root password for MySQL! You will need it later)
6. Execute the configuration, the installer should step through each step and give you green check marks at each stage
7. If you are stopped with a message saying that the server could not be started, your Windows Firewall may be blocking the MySQL port (default port is 3306). For problems related to error 1067 check the MySQL forum here
   1. Open Windows Firewall (Start → Settings → Control Panel → Windows Firewall)
   2. Under the "Exceptions" tab, click the "Add Port" button
      • Name: MySQL
      • Port number: 3306
      • (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

Deploy OpenMRS

1. Ensure that Tomcat is started by checking to see if icon in the tray is green (Windows install).
2. Download the latest stable release of OpenMRS.
3. Navigate to http://localhost:8080/manager/html and enter your Tomcat administrator creditials (username and password chosen when installing Tomcat)
4. In the Tomcat Web Application Manager, enter the location of the downloaded OpenMRS WAR file (openmrs.war) to deploy.
   1. 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.
   2. 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)

Starting your OpenMRS program

After you have finished deploying OpenMRS in Tomcat, and it is being displayed under applications, you can click on /OpenMRS tab (on the left side of the Tomcat Manager window) to start your application. The first time you do this, you will need to complete the initial configuration steps. After OpenMRS is configured, you will see a login page. You will need to login initially using Username: admin Password: test (both are in lowercase). 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).

Troubleshooting

When uploading the war file, Tomcat hangs and stops responding

This typically occurs when you have not defined a MySQL user account that OpenMRS can use to access the database or you have not granted this user full access to the openmrs database. The default username is test with password test. The default username/password can be overridden in the OPENMRS_RUNTIME_PROPERTIES.PROPERTIES configuration file. To fix this: use Navicat or the MySQL administration tool (available from mysql.com) to verify that you have a user with username "test" and password "test" and this user has full access to the openmrs database.

Cannot connect to Tomcat on port 8080

This port is sometimes used by other programs, such as Popfile and TivoServer. You can use the Windows "netstat -ao" command to discover if another process is using port 8080. Also, a case was found where software for a HP Laserjet 2840 printer was trying to use port 8005, which conflicts with Tomcat startup.

War file deploys in Tomcat but it won't start OpenMRS

Try this:

• Go to MySQL command line (accessible from Start menu)
• type the following lines and press enter after each one:
  • use OpenMRS;
  • create user openmrs identified by 'openmrs';
  • GRANT ALL ON openmrs.* TO 'openmrs'@'%';
• Go to C:\Documents and Settings\LocalService\Application Data\OpenMRS
• There should be a file there called OPENMRS-runtime.properties
• In this file, ensure it says the following:

### Database connection properties
connection.username=openmrs
connection.password=openmrs

• Also copy the file into C:\Documents and Settings\YOURUSERNAME\Application Data\OpenMRS where YOURUSERNAME is the name you use to log in to windows - this is in case tomcat looks there instead of in LocalService