Step 3 - Install Tomcat

Windows

1. Download the latest available version of Tomcat. You can use the .exe version, which installs Tomcat as a service or the .zip archive. (Tomcat 7 is the most preferred )
   
   1. Execute the file and install running the default settings 
   2. Accept the license agreement

1. Accept default destination folder
2. Accept HTTP/1.1 Connector Port 8080
3. Set Administrator login (username/password)
4. Accept the Java directory detected
5. Select Install Tomcat# After installation is complete you will need to change users roles by following this directory on your windows explorer
   1. C:\Program Files\Apache Software Foundation\Tomcat 7.0\conf
   2. Locate the file "tomcat-users.xml" and try to open it.
      1. Most likely your operating system will fail to detect the application that opens the file so make a right-click on the file then select down the menu Open With > Notepad
      2. You will notice that a text editor will show up then locate this character set <tomcat-users> The character set is located on line 18 of the file.
6. Open the Tomcat users file (e.g. C:\Program Files\Apache Software Foundation\Tomcat 7.0\conf\tomcat-users.xml) in a text editor.
7. 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")

<role rolename="tomcat"/>                                                     
<role rolename="admin"/>                                                      
<role rolename="manager"/>                                                    
<role rolename="manager-gui"/>
<user name="admin" password="XXXXXX" roles="tomcat,admin,manager,manager-gui"/>

Then save the file

1. Your operating system might bring an error message that indicates that you do not have sufficient privileges to save the file. Then it will ask you to save it in a different directory.
   1. You need to save the file in the current directory, right-click on the file "tomcat-users" and click on Properties, at the bottom of the menu.
   2. Navigate to the "Security" tab
   3. Select the username you are currently using on the machine
   4. Click the "Edit" button
   5. Permissions table will allow you to edit your privileges as a user.
   6. Click on Full Control then click OK and then OK again
   7. Now, you should be able to edit and save the file in the same directory.

(Optional) If you've installed Tomcat as a service, you can configure it to start automatically when the computer boots:

1. Start > Settings > Control Panel > Administrative Tools > Services
2. Right Click "Apache Tomcat" > Properties > Set "Startup Type" to Automatic
3. Click Start or restart your pc

Other operating systems

1. Download the zip archive of Tomcat 7.0.29
2. Unpack the zip file to a suitable location such as /opt on Linux or /Library on Mac OSX

sudo useradd tomcat6
cd /opt
sudo tar zxvf apache-tomcat-7.0.29.tar.gz
sudo ln -s apache-tomcat-7.0.29 tomcat7
sudo chown tomcat7.tomcat7 apache-tomcat-7.0.29

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)

<role rolename="tomcat"/>                                                     
<role rolename="admin"/>                                                      
<role rolename="manager"/>                                                    
<role rolename="manager-gui"/>
<user name="admin" password="XXXXXX" roles="tomcat,admin,manager,manager-gui"/>

As a package for Debian, Ubuntu & other Unix systems

1. Run the following command from a terminal

sudo apt-get install tomcat7

Open the Tomcat users file (e.g. /etc/tomcat7/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)

<role rolename="tomcat"/>                                                     
<role rolename="admin"/>                                                      
<role rolename="manager"/>                                                    
<role rolename="manager-gui"/>
<user name="admin" password="XXXXXX" roles="tomcat,admin,manager,manager-gui"/>

Turn off tomcat security flag in /etc/init.d/tomcat7 file: Find "TOMCAT7_SECURITY=yes" and change it to "TOMCAT7_SECURITY=no" For Tomcat 7, it is "no" by default.
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)

sudo mkdir /usr/share/tomcat7/.OpenMRS
sudo chown -R tomcat7:tomcat7 /usr/share/tomcat7/.OpenMRS/

To know more about the recommended application directory for OpenMRS refer to this discussion on Talk.

To start/stop/restart tomcat7, please type the following commands:

sudo service tomcat7 start
sudo service tomcat7 stop
sudo service tomcat7 restart

Security Enhancements

• In newest versions of Tomcat(> version 7), by default HttpOnly flag will be set by the server. But in older versions of Tomcat, it needs to set this flag through a configuration. The HttpOnly flag is an additional flag that is used to prevent an XSS (Cross-Site Scripting) exploit from taking access to the session cookie. Because one of the most known ways of subjecting to an XSS attack is access to the session cookie, and to subsequently hijack the victim’s session, the HttpOnly flag is a useful prevention mechanism where a client side script won't be able to access the session cookie from. To add the HttpOnly flag to session cookies in older versions of Tomcat, you need to edit the <TOMCAT_HOME>/conf/context.xml to add useHttpOnly="true" attribute as below:

  <Context useHttpOnly="true">
      <Manager pathname="" />
      <Valve className="org.apache.catalina.valves.CometConnectionManagerValve" />
  </Context>

  https://issues.openmrs.org/browse/TRUNK-3941