Requirements

You need Tomcat 5.0 or later.

If using Tomcat 5.5.22 or up, you need to set the system property org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH to true so encoded slashes are allowed.

Installation

To install Jenkins on Tomcat, simply copy jenkins.war to $TOMCAT_HOME/webapps, then access http://yourhost/jenkins.

If you are running Tomcat just to host Jenkins, then remove everything from $TOMCAT_HOME/webapps, and place jenkins.war as ROOT.war (Same case is important). Tomcat should expand this and create the ROOT directory, and you should see Jenkins in http://yourhost (if you accepted the Tomcat defaults - http://yourhost:8080) without any additional path. This also works nicely when you set up a virtual host, as it allows a single Tomcat instance to run multiple applications, yet users can still access your jenkins with URLs like http://jenkins.acme.org/ without any additional path. See the Tomcat documentation for more about how to set up a virtual host.

Upgrade

Simply overwrite your jenkins.war with the new version. Tomcat should automatically redeploy the application.

Setting JENKINS_HOME

Before starting Tomcat, set CATALINA_OPTS like this. This can be also used to specify JVM options to increase the heap size:

$ export CATALINA_OPTS="-DJENKINS_HOME=/path/to/jenkins_home/ -Xmx512m"
$ catalina.sh start

Or if that fails for some reason, you should still be able to use the environment variable:

$ export JENKINS_HOME=/path/to/jenkins_home/
$ catalina.sh start

Or in the Tomcat context descriptor of the servlet, which allows a different setting per servlet:

<Context ...>
  <Environment name="JENKINS_HOME" value="/path/to/jenkins_home/" type="java.lang.String"/>
</Context>

Securing Jenkins on Tomcat

Tomcat by default stores the user database in an XML file called $TOMCAT_HOME/conf/tomcat-users.xml. You can add the following lines to this file to create an admin user.

<role rolename="admin"/>
<user username="jenkins-admin" password="secret" roles="admin"/>

i18n

Some versions of Tomcat (such as 5.0.28) uses iso-8859-1 to decode URLs, which is in a clear violation of the relevant RFCs. To fix this problem, add the following URIEncoding attribute to the connector definition in $TOMCAT_HOME/conf/server.xml.

<Connector port="8080" URIEncoding="UTF-8"/>

Other people reported that a presence of RequestDumperValve would also cause a problem.

Relevant Issues

See the list of issues filed that are specifically marked relevant to Tomcat.

There is also a known issue in Tomcat 6.0.21 to 6.0.26 that may cause some requests to hang.

Tomcat from XAMPP

If you are using XAMPP's tomcat installation, and you have Java > 1.5, then you need to remove the following jars from the common\lib directory, otherwise you will get FileNotFound exceptions from the changelog.xml generator:

xalan.jar
xercesImpl.jar
xercesSamples.jar

Tomcat from Ubuntu

If you get Tomcat from Ubuntu via apt-get, Jenkins will report an error citing the security permission issue. This is because Tomcat in Ubuntu comes with the security manager on by default. This can be disabled by modifying /etc/default/tomcat5 (version number will be different depending on which version of Tomcat you install.) See JENKINS-719 for more details.

Tomcat from Debian

Fix security issues adding the next lines at /etc/tomcat5.5/policy.d/04webapps.policy:

grant codeBase "file:/var/lib/tomcat5.5/webapps/jenkins/-" {
    permission java.security.AllPermission;
};

Set Jenkins home at file /etc/default/tomcat5.5:

CATALINA_OPTS="-DJENKINS_HOME=/var/lib/tomcat5.5/webapps/jenkins/"

Tomcat from Windows

GUI Testing in Windows

Most Windows services -- including those run with the option "Allow service to interact with desktop" in Windows XP and Vista -- do not have access to many of the computer's resources, including the console display. This may cause Automated GUI Tests to fail if you are running Apache Tomcat as a Windows Service and are doing any GUI testing. This is true at least for AWT and Abbot frameworks. A typical error might look similar to this:

[junit] \# An unexpected error has been detected by HotSpot Virtual Machine:
[junit] \#
[junit] \# EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x6d07baf4, pid=3260, tid=288
[junit] \#
[junit] \# Java VM: Java HotSpot(TM) Client VM (1.5.0_09-b03 mixed mode, sharing)
[junit] \# Problematic frame:
[junit] \# C [awt.dll+0xbaf4|awt.dll+0xbaf4]
[junit] \#

This limitation can be resolved by not running Tomcat as a Windows Service, but instead through a "Scheduled Task" as an Application that runs at logon. There are several options for doing this, an example would be to run "$TOMCAT_HOME\bin\tomcat5.exe". When setting up the scheduled task in Windows Vista consider choosing the check-box for "Run with highest privileges" from the general tab, as this removes the need to always provide administrator privileges and may resolve other issues as well.

*Note: This workaround/fix may or may not require an admin to be logged in during testing. Running your tests while logged in as a standard user this is fine, but some modifications may need to be made for your individual configuration.

Jenkins : Tomcat