You need Tomcat 5.0 or later.
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.acme.org/ without any additional path. See the Tomcat documentation for more about how to set up a virtual host.
Simply overwrite your hudson.war with the new version and delete the hudson folder in webapps (exploded war). Tomcat should automatically redeploy the application.
Before starting Tomcat, set CATALINA_OPTS like this. This can be also used to specify JVM options to increase the heap size:
Or on Tomcat 1.6+ CATALINA_OPTS has been replaced by JAVA_OPTS (Thanks to Ronoaldo Pereira):
Or if that fails for some reason, you should still be able to use the environment variable:
If you see permgen errors when running Tomcat, edit the catalina.sh file on *NIX systems to assign the following options
Or on windows use the Configure Tomcat GUI Java panel to set the same additional options and restart 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.
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.
Other people reported that a presence of RequestDumperValve would also cause a problem.
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.
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:
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 issue #719 for more details.
Fix security issues adding the next lines at /etc/tomcat5.5/policy.d/04webapps.policy:
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:
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.