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.
Related reads
- Similar instruction for Confluence (http://confluence.atlassian.com/display/DOC/Configuring+Tomcat's+URI+encoding)
- 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, 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.
19 Comments
Unknown User (djcarr)
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 ).
Unknown User (davida)
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.
Unknown User (luca.candela@gmail.com)
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.
Unknown User (jonathan@phillipoux.net)
The section on "Tomcat from Debian" suggests setting:
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.
Unknown User (cswingler)
@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
Unknown User (westfox)
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.
Unknown User (alejandropg@autentia.com)
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
Unknown User (evoturvey@gmail.com)
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
Unknown User (dupuisc1)
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):
So, how to see and use my plugins in graphical Hudson tool?
Unknown User (ravenman)
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
. This is most likely a permission problem.
What is wrong ? This is a bug ?
Unknown User (ravenman)
Fixed in the 1.351 version. Thanks.
Unknown User (ronoaldo@gmail.com)
Here is a small tutorial to get Hudson 1.352 working under Tomcat 6/Ubuntu 9.10:
Notes about this Wiki information:
Unknown User (slide.o.mix@gmail.com)
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.
Unknown User (msinghal@in.sopragroup.com)
Thanks .. it helped me a lot ...
Unknown User (test_hendia)
installation problem with Jenkins.
hello, my problem is:
I've tried to install it suggests: http://pkg.jenkins-ci.org/redhat/
but I have the problem to get access to my web server: HTTP://myhost:8080/jenkins
Error
Unable to create the home directory '/usr/share/tomcat5/.jenkins'. This is most likely a permission problem.
To change the home directory, use
JENKINS_HOME
environment variable or set theJENKINS_HOME
system property. See Container-specific documentation for more details of how to do this.I'm new at this, and I can not really how to install, please if I could explain in more detail how to perform the installation.
The steps performed were as follows:
1. cd /etc/yum.repos.d/
2. wget -O /etc/yum.repos.d/jenkins.repo http://pkg.jenkins-ci.org/redhat/jenkins.repo
3. rpm --import http://pkg.jenkins-ci.org/redhat/jenkins-ci.org.key
4. yum -y install jenkins
5. /etc/init.d/jenkins start
6. Download jenkins.war, and copy in: /var/lib/tomcat5/webapps/
7. Firefox: http://myhost.8080/jenkins
8. error:
Unable to create the home directory '/usr/share/tomcat5/.jenkins'. This is most likely a permission problem.
To change the home directory, use
JENKINS_HOME
environment variable or set theJENKINS_HOME
system property.See Container- specific documentation for more details of how to do this.
9. Help.
- Do not understand about: Setting JENKINS_HOME and Jenkins on Securing Tomcat
Unknown User (mrkk)
Even though I am using
<Connector port="10080" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="10443" URIEncoding="UTF-8" />
I still get
Your container doesn't use UTF-8 to decode URLs. If you use non-ASCII characters as a job name etc, this will cause problems. See Containers and Tomcat i18n for more details.
Unknown User (venkatannangi)
Hi we have more than 100 jobs to load when we start the tomcat server it is taking more than 25 minutes to get Jenkins ready for the usage to load job and build information.
Is there any way we can configure Jenkins application for lazy loading of jobs?
Unknown User (ahmed_mekkaoui06)
i have a ERROR 404 when i running jenkins from TOMCAT im using :
And this is the steps :
finaly run tomcat

And this is the result :
Unknown User (akmjenkins)
We are using Jenkins V.2.121.3 and tomcat V.8.5.28. And we are seeing frequent GUI hung even the activities are up and running in the individual node(s). We do not have any job in master. Any recommendation for tomcat upgrade !? Additional information JDK V.1.8.0_181 (recently upgraded from V.1.8.0_162).