Tomcat

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.acme.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.

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 reads

  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

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, 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.

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

Labels:

Enter labels to add to this page:
Wait Image 
Looking for a label? Just start typing.
  1. Dec 09, 2008

    djcarr says:

    Is there a way to restart the hudson process without restarting Tomcat? The Act...

    Is there a way to restart the hudson process without restarting Tomcat?

    The Active Directory plugin doesn't seem to like Tomcat being restarted (see https://hudson.dev.java.net/issues/show_bug.cgi?id=2708 ).

  2. May 19, 2009

    David Aldrich says:

    I think the Upgrade paragraph is incorrect. Tomcat documentation states: "If yo...

    I think the Upgrade paragraph is incorrect. Tomcat documentation states:

    "If you redeploy an updated WAR file, be sure to delete the expanded directory when restarting Tomcat, so that the updated WAR file will be re-expanded (note that the auto deployer, if enabled, will automatically expand the updated WAR file once the previously expanded directory is removed)."

    So you must delete the hudson folder for the new war to be expanded.

  3. Jul 25, 2009

    Luca Candela says:

    One note: windows users might not be aware that ROOT.war is case sensitive, so m...

    One note: windows users might not be aware that ROOT.war is case sensitive, so make sure you rename hudson.war to ROOT.war (and not root.war or Root.war) or it will not work. Just adding this because it took me 20 minutes to figure out what's wrong and might be saving the hassle to the next person with the same problem.

  4. Aug 10, 2009

    Jonathan Clarke says:

    The section on "Tomcat from Debian" suggests setting: HUDSON_HOME=/var/lib/tomc...

    The section on "Tomcat from Debian" suggests setting:

    HUDSON_HOME=/var/lib/tomcat5.5/webapps/hudson/
    

    This is really not a good idea, since this directory is where the Hudson WAR is deployed - so when upgrading, it (and all your configuration) will be deleted!

    Use some other directory, not under the webapps directory.

  5. Sep 17, 2009

    Chris Swingler says:

    @djcarr: You should be able to use the Tomcat Manager to reload a webapp witho...

    @djcarr:

    You should be able to use the Tomcat Manager to reload a webapp without restarting Tomcat.Try http://yourhost/manager/html. ; You may need to set up a manager user.

    See http://tomcat.apache.org/tomcat-5.5-doc/manager-howto.html

  6. Sep 24, 2009

    westfox says:

    For windows tomcat 5.5 or later , using apache tomcat monitor to config tomcat, ...

    For windows tomcat 5.5 or later , using apache tomcat monitor to config tomcat, tab "Java", "java options" add "-DHUDSON_HOME=<path to you want>" is OK.

  7. Oct 26, 2009

    Alejandro Pérez García says:

    I wrote a Spanish tutorial about the instalation and first steps on Tomcat &nbs...

    I wrote a Spanish tutorial about the instalation and first steps on Tomcat

        http://www.adictosaltrabajo.com/tutoriales/tutoriales.php?pagina=hudsonInstalacionTomcat

    He escrito un tutorial en Español sobre la instalación y primeros pasos en Tomcat

        http://www.adictosaltrabajo.com/tutoriales/tutoriales.php?pagina=hudsonInstalacionTomcat

  8. Nov 17, 2009

    Kenneth P. Turvey says:

    I wrote a tutorial on installing hudson to use git and grails, but it also inclu...

    I wrote a tutorial on installing hudson to use git and grails, but it also includes all the information necessary to get it working with Tomcat under Ubuntu:

    http://www.electricsenator.net/2009/10/03/1254618530821.html

  9. Dec 07, 2009

    dupuis christophe says:

    I upgraded the latest Hudson version 1.336 (from 1.332 but I'm not sure). Upgra...

    I upgraded the latest Hudson version 1.336 (from 1.332 but I'm not sure).

    Upgrade is working, all jobs are found, but my plugins disappeared in graphical Hudson tool.In <HUDSON_HOME> directory, all my plugins are still present.

    I tried following things without success (with and without stop/start hudson):

    • with plugin manager: I selected again my plugins
    • with advanced plugin manager: I uploaded my plugins
    • I deleted <HUDSON_HOME>/update-center.json

    So, how to see and use my plugins in graphical Hudson tool?

  10. Mar 02, 2010

    Maxwell Draven says:

    I installed the latest Hudson version 1.348 (from the war package) on CEntOS 5.4...

    I installed the latest Hudson version 1.348 (from the war package) on CEntOS 5.4 and Tomcat6, I added 

    CATALINA_OPTS="-DHUDSON_HOME=/usr/share/tomcat6/webapps/hudson"

    To the /etc/tomcat6/tomcat6.conf file.

    But when I'm trying get to Hudson main page, it shows this:

    Unable to create the home directory

    Unknown macro: {0}

    . This is most likely a permission problem.

    What is wrong ? This is a bug ?

    1. Mar 16, 2010

      Maxwell Draven says:

      Fixed in the 1.351 version. Thanks.

      Fixed in the 1.351 version. Thanks.

  11. Mar 24, 2010

    Ronoaldo Pereira says:

    Here is a small tutorial to get Hudson 1.352 working under Tomcat 6/Ubuntu 9.10:...

    Here is a small tutorial to get Hudson 1.352 working under Tomcat 6/Ubuntu 9.10:

    • Install your Ubuntu Server (This may work with Debian too, not tested yet).
    • Install the Tomcat Conteiner and the Manager App:
      # apt-get install tomcat6 tomcat6-admin
      
    • Download Hudson 1.352 war and upload it via your Tomcat Manager Webapp at http://yourserver:8080/manager/html (You may need to add a user under Tomcat to have it running properly. See /etc/tomcat6/tomcat-users.xml):
      • If you need to enable authentication under Hudson, you need to have the file groovy-1.6.3.jar in Hudson's WEB-INF/lib directory or some erros will apear. I've added it by installing the groovy package, and coping the file to the Hudson webapp directory.
        # apt-get install groovy
        # cp /usr/share/groovy/lib/groovy-1.6.3.jar /var/lib/tomcat6/webapps/hudson/WEB-INF/lib/
        
    • Now, you must configure Tomcat permissions to your Hudson app. Is a good Idea to change the HUDSON_HOME directory too, so when upgrading your install will not delete your settings (CHANGE /home/hudson/ int the following lines to a directory you choose to store Hudson settings and installed plugins. Remember to chown the directory to tomcat6 user, or you may have some probmems!)
      • First, change the Hudson home directory by adding this settings to your /etc/default/tomcat6 file:
        JAVA_OPTS="-DHUDSON_HOME=/home/hudson/" # If you already have other settings in this variable, just add this one separed by whitespaces.
        
      • Then, create a file at /etc/tomcat6/policy.d/, named 04hudson.policy, with this contents:
        grant codeBase "file:/home/hudson/-" {
            permission java.security.AllPermission;
            permission java.io.FilePermission "/home/hudson/-", "read,write,delete";
            permission java.io.FilePermission "/var/lib/tomcat6/webapps/hudson/-", "read,write,delete";
        };
        
        grant codeBase "file:/var/lib/tomcat6/webapps/hudson/-" {
            permission java.security.AllPermission;
            permission java.io.FilePermission "/home/hudson/-", "read,write,delete";
        };
        
      • The permissions above will let you install your Hudson plugins (like Jabber IM, and others), and have them working properly. I'm not shure if setting all permissions is a security risk, any one have some tips on that?
    • Now, restart your Tomcat, and access your running Hudson setup!
      # service tomcat6 restart
      

    Notes about this Wiki information:

    • In the above Wiki, the option CATALINA_OPTS don't work for Tomcat 6, use JAVA_OPTS insted.
    • The permissions are needed if you change your Hudson home, or the plugins will install, but the may not work properly.
    • Restarting Hudson via the "Restart when no jobs are running" button (usualy, when installing plugins) causes Tomcat to shutdown! I use the Tomcat Manager web app to restart hudson context, by stopping and starting it again. Is this a bug on Hudson or Tomcat? Is this because of the permissions set to all?
    • Ubuntu already ships a Hudson daemon setup, if you don't need to run it under a Tomcat Conteiner, simply install it by running:
      # apt-get install hudson
      
  12. May 11, 2010

    Slide Earl says:

    On Windows, if you are running Tomcat as a Windows Service, to set the options f...

    On Windows, if you are running Tomcat as a Windows Service, to set the options for the JVM (like setting CATALINA_OPTS or JAVA_OPTS) use the Tomcat Service Manager. This is either a tray application, or you can run the manager directly via $CATALINA_HOME\bin\tomcat6w.exe, set the options under the "Java" tab and hit "Apply" to apply them. Each options goes on it's own line.

  13. Jan 04, 2011

    Mohit Singhal says:

    Thanks .. it helped me a lot ...

    Thanks .. it helped me a lot ...

  14. Nov 07, 2011

    Mohammad Arifur Rahman says:

    I have just installed hudson on tomcat6. OS is CentOS 6 (64-bit). Setting HUDSO...

    I have just installed hudson on tomcat6. OS is CentOS 6 (64-bit).

    Setting HUDSON_HOME="/root/hudson", I was getting an error saying "Unable to create the home directory". I got success after I set HUDSON_HOME="/usr/share/tomcat6/.hudson".

    It might be worthwhile to mention that in both cases I set folder permission correctly, also the user tomcat was given ownership.

    So, my guess is there is an issue with setting HUDSON_HOME in /root.