Page tree
Skip to end of metadata
Go to start of metadata

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.  At the time of writing, any version less than Tomcat 7.0 fails to properly launch the OpenMRS application.
    1. Execute the file and install running the default settings o 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 6.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 6.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 6.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-6.0.29.tar.gz
sudo ln -s apache-tomcat-6.0.29 tomcat6
sudo chown tomcat6.tomcat6 apache-tomcat-6.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

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)
sudo mkdir /usr/share/jetty
cd /usr/share/jetty
sudo mv /pathtojetty/jetty-distribution-(version).tar.gz .
sudo tar xfz jetty-distribution-(verstion).tar.gz
sudo mv jetty-distribution-(version)/* .
sudo rm -rf jetty-distribution-(version)

Now to make it start when you start the system and make Jetty a service

sudo cp bin/jetty.sh /etc/init.d/jetty

Edit /etc/init.d/jetty to include the following two lines after the comments so Jetty knows where your Java and Jetty directories are.

JAVA_HOME=(path to java)
JETTY_HOME=/usr/share/jetty  //or where your jetty installation directory

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.

sudo /etc/init.d/jetty start

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

 

 

  • No labels

2 Comments

  1. Also it would be important to add permissions to the tomcat location on var/lib in ubuntu

    sudo chown -R tomcat7 /var/lib/tomcat7
  2. Neha Goel i see you made edits to the paths. But on some systems, those are the actual paths. So i think you would just add alternative paths for other systems instead of overwriting them.