Latest revision as of 08:45, 7 March 2012

	Using Apache Tomcat as a Container

Requirements

You need Tomcat 5.0 or later.

Installation

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

If you are running Tomcat just to host Hudson, then remove everything from $TOMCAT_HOME/webapps, and place hudson.war as ROOT.war. Tomcat should expand this and create the ROOT directory, and you should see Hudson 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 hudson with URLs like http://hudson.example.org/ without any additional path. See the Tomcat documentation for more about how to set up a virtual host.

Upgrade

Simply overwrite your hudson.war with the new version and delete the hudson folder in webapps (exploded war). Tomcat should automatically redeploy the application.

Setting HUDSON_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="-DHUDSON_HOME=/path/to/hudson_home/ -Xmx512m"
$ catalina.sh start

Or on Tomcat 1.6+ CATALINA_OPTS has been replaced by JAVA_OPTS (Thanks to Ronoaldo Pereira):

$ export JAVA_OPTS="-DHUDSON_HOME=/path/to/hudson_home/ -Xmx512m"
$ catalina.sh start

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

$ export HUDSON_HOME=/path/to/hudson_home/
$ catalina.sh start

Increasing Tomcat PermGen space

If you see permgen errors when running Tomcat, edit the catalina.sh file on \*NIX systems to assign the following options

JAVA_OPTS="-Xmx1024m -XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m -XX:MaxPermSize=256m"

Or on windows use the Configure Tomcat GUI Java panel to set the same additional options and restart Tomcat.

Running Hudson as the Tomcat Root Application

To run Hudson as the root application (accessed simply using "host:port/") within Tomcat add the following to the server.xml file (found in the Tomcat home /conf) In the <Engine name="Catalina" ... > locate the <Host name="localhost" ...> element and insert within that the following:

<Context path="" docBase="${catalina.home}/hudson" 
         reloadable="false" 
         useHttpOnly="true">
  <Valve className="org.apache.catalina.authenticator.NonLoginAuthenticator" 
         disableProxyCaching="false" />
</Context>

This assumes that the Hudson WAR has been unpaked into the /hudson directory within the Tomcat home

Note that the <Valve .../> element is important if you are running hudson secured. Failure to add this statement will result in Tomcat supressing the cache directives on all of the static artifacts such as gif files and vastly increase the loading on the server as it will have to repeatedly serve up these artifacts rather than clients picking it up from their caches.

Proxying  to Tomcat Through Apache

Related to the desire to run Hudson as the root application in Tomcat you may also want to run it on the default HTTP port (80).  Given the security constraints on *nix systems any process that needs to listen on this port needs to be started as root.  However, we do not recommend that you run Hudson as the root user and Apache tomcat does not have the ability to startup as root but then downgrade to a less privileged user. Therefore, we recommend that you use the Apache HTTPD server to proxy through to Tomcat running on a different port. Apache HTTPD does have the ability to run-as a less priviledged user. 

Assuming that you are running Apache httpd 2.2 or above you will need mod_proxy and mod_proxy_ajp loaded e.g.

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

Then define a VirtualHost entry to pass all port 80 traffic through to Tomcat:

NameVirtualHost *:80
 
<VirtualHost *:80>
 
  ServerName myserver.example.com
  ServerAlias ci.hudson-ci.org
 
  ProxyPass / ajp://localhost:8009/
  ProxyPassReverse / ajp://localhost:8009/
 
</VirtualHost>

In this case Port 8009 is the AJP connector port which will match that defined in the Tomcat server.xml file. for example (some parts omitted):

<?xml version='1.0' encoding='utf-8'?>
<Server port="8005" shutdown="SHUTDOWN">
  <Service name="Catalina">
    <Connector port="8080" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443" />
 
    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
 
    <Engine name="Catalina" defaultHost="localhost">
	...
    </Engine>
  </Service>
</Server>

Securing Hudson 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="hudson-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.

Related Reading

1. Similar instruction for Confluence
2. John O'Conner's blog entry about his experiment. See Elliotte(id:elharo)'s comment in particular,

Relevant Issues

There is a known issue (HUDSON-6473 - Deadlock when rendering test result graphs) 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, Hudson 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 HUDSON-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/hudson/-" {
    permission java.security.AllPermission;
};

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