Skip to Content

Wiki source code of Tomcat Installation

Last modified by Eleni Cojocariu on 2026/05/28 16:23
Hide last authors
Dmitry Bakbardin 13.4 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Vincent Massol 11.1 4
Eleni Cojocariu 101.2 5 {{warning}}
Eleni Cojocariu 101.21 6 Documentation is being refactored at: [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
Eleni Cojocariu 101.2 7 {{/warning}}
8
Vincent Massol 5.2 9 = Installation Steps =
vmassol 1.1 10
Eleni Cojocariu 101.38 11 See [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
Thomas Mortagne 100.2 12
Vincent Massol 11.1 13 == Activate headless mode ==
mawoki 10.1 14
Eleni Cojocariu 101.26 15 See [[Headless Mode Activation on Apache Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.headless-mode-activation-apache-tomcat.WebHome]].
mawoki 10.1 16
Vincent Massol 11.1 17 == Optional configuration ==
mawoki 9.1 18
Eleni Cojocariu 101.24 19 See [[Enable HTTP Compression (gzip)>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.enable-http-compression-gzip.WebHome]].
mawoki 9.1 20
HoaniCross 19.1 21 == Policy configuration ==
22
Eleni Cojocariu 101.35 23 See [[Java Security Manager in Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-security-manager.WebHome]].
HoaniCross 19.1 24
Thomas Mortagne 93.1 25 == HTTP reverse proxy ==
Dmitry Bakbardin 13.4 26
Thomas Mortagne 92.1 27 For a [[variety of reasons>>https://en.wikipedia.org/wiki/Reverse_proxy||rel="__blank"]], it is not ideal to allow users to connect directly to tomcat. So it's generally recommended to put an HTTP reverse proxy such as Apache HTTP Server or Nginx in front of it.
Thomas Mortagne 89.1 28
Thomas Mortagne 93.1 29 === Using Apache HTTP Server ===
Thomas Mortagne 89.1 30
Eleni Cojocariu 101.4 31 See [[Apache Server Key Configurations>>documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]] and the tutorials:
Thomas Mortagne 89.1 32
Eleni Cojocariu 101.4 33 * [[Configure Apache HTTP Server as a Proxy on a Linux OS>>documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.configure-apache-server-linux.WebHome]].
34 * [[Configure Apache HTTP Server as a Proxy on a Windows OS>>documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.configure-apache-server-windows.WebHome]].
35
Thomas Mortagne 93.1 36 === Using Nginx ===
Thomas Mortagne 89.1 37
Eleni Cojocariu 101.3 38 See [[NginX Server Key Configurations>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.WebHome]] and the tutorial to [[Set up NginX Proxy Server>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]].
Dmitry Bakbardin 13.4 39
Thomas Mortagne 93.1 40 ==== Http (unsecure) ====
Eleni Cojocariu 101.6 41
Eleni Cojocariu 101.5 42
43 See [[Set up NginX Proxy Server>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]].
Craig Wright 30.1 44
Thomas Mortagne 93.1 45 ==== Https (secure) ====
Craig Wright 30.1 46
Eleni Cojocariu 101.7 47 See [[More Configurations for the NginX HTTP Proxy Server>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]].
Eleni Cojocariu 101.25 48 See [[Configure Tomcat to Find Proxy Headers>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.find-proxy-headers.WebHome]].
Craig Wright 30.1 49
Thomas Mortagne 93.1 50 ==== Proxying and tunnels ====
Paul Libbrecht 51.1 51
Eleni Cojocariu 101.8 52 See [[Reverse Proxy and SSH Tunneling>>documentation.xs.admin.installation.http-reverse-proxy.ssh-tunneling.WebHome]].
Paul Libbrecht 51.1 53
Jan-Paul Kleijn 67.1 54 = Recommendations =
Thomas Mortagne 65.1 55
Jan-Paul Kleijn 67.1 56 == Default encoding ==
Thomas Mortagne 65.1 57
Eleni Cojocariu 101.33 58 See [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
Thomas Mortagne 65.1 59
Vincent Massol 12.1 60 = Troubleshooting =
Vincent Massol 1.16 61
Vincent Massol 5.2 62 == Out Of Memory Error ==
Vincent Massol 1.16 63
Vincent Massol 64.2 64 === General Memory Settings ===
65
Eleni Cojocariu 101.23 66 See [[Configure Java Memory for Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.configure-java-memory.WebHome]].
Vincent Massol 1.16 67
Vincent Massol 64.2 68 === Max number of threads ===
69
Eleni Cojocariu 101.34 70 See [["Unable to Create Native Thread" Errors on Debian Systems>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.unable-create-native-thread-errors-debian-systems.WebHome]].
Rainer Stransky 63.1 71
Vincent Massol 5.2 72 == Java Security Manager ==
Vincent Massol 1.16 73
Eleni Cojocariu 101.36 74 See [[Java Security Manager in Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-security-manager.WebHome]]
Vincent Massol 1.16 75
Vincent Massol 44.1 76 == Allowing "/" and "\" in page names ==
Vincent Massol 11.1 77
Eleni Cojocariu 101.22 78 See [[Configure Tomcat to Allow Slash and Backslash in Page Names>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.allow-slash-backslash-page-names.WebHome]].
Vincent Massol 11.1 79
Vincent Massol 56.2 80 === Apache front-end server ===
Ludovic Dubost 56.1 81
Vincent Massol 56.2 82 Note that if you're using the Apache web server as a front-end, you also need to [[configure Apache to allow encoded / and \>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]] (##AllowEncodedSlashes NoDecode##) and also make sure to use ##nocanon## on the [[ProxyPass line used>>https://httpd.apache.org/docs/2.4/mod/mod_proxy.html]].
Vincent Massol 44.1 83
Vincent Massol 21.1 84 == NotSerializableException ==
85
Eleni Cojocariu 101.27 86 See [[Session Deserialization Errors in Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.session-deserialization-errors.WebHome]].
Vincent Massol 21.1 87
Vincent Massol 12.1 88 == SEVERE: Error listenerStart ==
89
Eleni Cojocariu 101.28 90 See [["Severe: Error listenerStart" in Logs>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.severe-error-listenerstart-error-logs.WebHome]].
Vincent Massol 12.1 91
Simon Urli 46.1 92 == Parameter count exceeded allowed maximum ==
93
Eleni Cojocariu 101.29 94 See [[Parameter Count Exceeded Allowed Maximum>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.parameter-count-exceeded-allowed-maximum.WebHome]].
Simon Urli 46.1 95
Vincent Massol 59.1 96 == ThreadLocal Errors ==
Vincent Massol 58.1 97
Eleni Cojocariu 101.30 98 See [[ThreadLocal Memory Leak Warnings on Shutdown>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.threadlocal-memory-leak-warnings-shutdown.WebHome]].
Vincent Massol 58.1 99
Vincent Massol 98.1 100 == Request header is too large ==
101
Eleni Cojocariu 101.32 102 See [[Request Header is Too Large>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.troubleshooting.request-header-large.WebHome]].
Vincent Massol 98.1 103
Vincent Massol 54.1 104 = Old Instructions =
105
106 Note that [[Tomat 7 is no longer supported>>dev:Community.SupportStrategy.ServletContainerSupportStrategy.WebHome]].
107
108 {{error}}
109 The Tomcat project has brought a change in the [[way they handle ##RequestDispatcher##>>https://bz.apache.org/bugzilla/show_bug.cgi?id=59317]] which has caused [[regressions in XWiki>>https://jira.xwiki.org/browse/XWIKI-13556]] for some versions of Tomcat. Thus you should **not** use the following Tomcat versions:
110
111 * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10)
112 * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5)
113 * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37)
114 * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71)
115
116 There is an important Classloader related bug in 8.0.32 which makes impossible to use the code macro or write Python scripts so you should avoid this version if possible. See https://bz.apache.org/bugzilla/show_bug.cgi?id=58999.
117 {{/error}}
118
119 * XWiki 12.0+ requires a Tomcat version >= 8 since it requires Servlet 3.1+
120 * Older versions of XWiki require a Tomcat version >= 7 since it requires Servlet 3.0+
Jan-Paul Kleijn 77.1 121 * Tomcat 7 is not using URF-8 by default. Edit the ##conf/server.xml## file to set the UTF-8 encoding:(((
Jan-Paul Kleijn 76.1 122 {{code language="none"}}
123 <Connector port="8080"
124 ...
125 URIEncoding="UTF-8">
126 </Connector>
Vincent Massol 54.1 127 {{/code}}
128 )))

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected