Overview

NOTE: we are in the process of making an install wizard that will greatly simplify the installation process You can also try our OpenMRS Appliance..

Steps Involved

1. Install Firefox
2. Install Java 5+ runtime environment
3. Install Tomcat 5.5+
4. Install MySQL 5+
5. Build the OpenMRS database
6. Create a runtime configuration
7. Install OpenMRS

* 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 ( 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 username="tomcat" password="tomcat" roles="tomcat,admin,manager"/>

10. (Optional) 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

Build the OpenMRS Database

1. Download the latest demo database script
   • Openmrs-all.zip
2. Extract with WinZip
3. Open the MySQL Command Line Client (Start → Programs → MySQL → MySQL Server 5.0 → MySQL Command Line Client)
4. Enter your MySQL root password (defined as you installed MySQL)
5. For a clean database, execute the openmrs-all.sql script, for a database populated with some demo information, see below

   example: source c:/path/to/script/openmrs-all.sql

6. Download the latest diff files (from the Downloads page select the most recent ***.mysqldiff.sql file).
   • OpenMRS Downloads Page

1. The diff files update the database model with the latest changes made by the developers to support the new version/build of OpenMRS.

2. Execute the diff files against the database (note to change the "\" that Windows uses for directories to "/" this works best when the .sql files are placed in a directory path with no spaces), also remember the ";" at the end of each line

   use openmrs;

   source c:/path/to/script/openmrs_1.1.0-to-latest-mysqldiff.sql;

1. For a demo database download the latest x-creatdb-from-scratch.sql and source ONLY this file as listed above.
2. Finally create the username and password that OpenMRS will use to connect to the database. Note you will specify this username later in the Runtime properties file. The "openmrs.*" specifies which database to grant privileges on. The TO 'username' specifies the user for the database, and the IDENTIFIED BY 'password' specifies the password.

    GRANT ALL ON openmrs.* TO 'username'@'%' IDENTIFIED BY 'password';

Runtime Configuration

1. Using a text editor, create a runtime configuration file
   • We typically name this file OPENMRS-runtime.properties
   • You can get the basic (default) settings from this page in the middle box
   • Note to edit the lines in the Runtime Properties File to correspond to the username and password you specified in the last part of the database setup:

1. connection.username=username
   

   connection.password=password

   connection.url=jdbc:mysql://localhost:3306/openmrs?autoReconnect=true

1. Now you must create a system variable that directs the OpenMRS application to the runtime configuration file
   • Right-click on the My Computer icon (typically on the desktop or under the Start menu) and select "properties"
   • Under the "Advanced" tab, click the "Environment Variables" button
   • You should see two sections: one for user variables and another for system variables
   • Click the "New" button within the System Variables section (near the bottom)

   Variable name: OPENMRS_RUNTIME_PROPERTIES_FILE

   Variable value: C:\path\to\your\OPENMRS-runtime.properties

   (note: you will need to specify the path to the runtime configuration file you created earlier)

2. Reboot (you must reboot for the new system variable to be available to all programs)

Deploy OpenMRS

1. Ensure that Tomcat is started by checking to see if icon in the tray is green.
2. Navigate to http://localhost:8080/manager/html and enter your Tomcat administrator creditials (username and password chosen when installing Tomcat)
3. In the Tomcat Web Application Manager, enter the location of the OpenMRS WAR file (openmrs.war) to deploy. (Note that the OpenMRS.WAR file is most easily downloaded with Mozilla FireFox. Internet Explorer tries to open the file as a Zip file). 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.
4. 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)

Install Navicat

This step is optional. Navicat is a commercial tool we have found handy for interacting with MySQL. If you prefer a free alternative, you could use the Query Browser provided by MySQL.

1. Install Navicat (navicat2005ent.exe or get trial version from Navicat's website)
   1. Accept default location (C:\Program Files\PremiumSoft Navicat)
   2. Accept Program shortcut (PremiumSoft Navicat)
   3. Create a desktop icon
   4. Select Install
2. Configuration
   1. Start Navicat
   2. select Connection
   3. Enter Connection Name (Localhost) and select defaults

   Host Name / IP address: localhost

   Port: 3306

   User name: root

   Password: password

3. Create Database (Navicat) — if not created previously
   1. Right Click localhost and select "Execute Batch File"
   2. Run the openmrs-all.sql script that is inside the Image:Openmrs-all.zip file.

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. 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