Skip to Content

Wiki source code of Tomcat Installation

Last modified by Eleni Cojocariu on 2026/05/28 16:23
Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 {{warning}}
6 Documentation is being refactored at: [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
7 {{/warning}}
8
9 = Installation Steps =
10
11 See [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
12
13 == Activate headless mode ==
14
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]].
16
17 == Optional configuration ==
18
19 See [[Enable HTTP Compression (gzip)>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.enable-http-compression-gzip.WebHome]].
20
21 == Policy configuration ==
22
23 See [[Java Security Manager in Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-security-manager.WebHome]].
24
25 == HTTP reverse proxy ==
26
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.
28
29 === Using Apache HTTP Server ===
30
31 See [[Apache Server Key Configurations>>documentation.xs.admin.installation.http-reverse-proxy.apache-key-configurations.WebHome]] and the tutorials:
32
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
36 === Using Nginx ===
37
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]].
39
40 ==== Http (unsecure) ====
41
42
43 See [[Set up NginX Proxy Server>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.WebHome]].
44
45 ==== Https (secure) ====
46
47 See [[More Configurations for the NginX HTTP Proxy Server>>documentation.xs.admin.installation.http-reverse-proxy.nginx-key-configurations.set-nginx.configurations.WebHome]].
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]].
49
50 ==== Proxying and tunnels ====
51
52 See [[Reverse Proxy and SSH Tunneling>>documentation.xs.admin.installation.http-reverse-proxy.ssh-tunneling.WebHome]].
53
54 = Recommendations =
55
56 == Default encoding ==
57
58 See [[Configure Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.WebHome]].
59
60 = Troubleshooting =
61
62 == Out Of Memory Error ==
63
64 === General Memory Settings ===
65
66 See [[Configure Java Memory for Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.configure-java-memory.WebHome]].
67
68 === Max number of threads ===
69
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]].
71
72 == Java Security Manager ==
73
74 See [[Java Security Manager in Tomcat>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.configure-tomcat.java-security-manager.WebHome]]
75
76 == Allowing "/" and "\" in page names ==
77
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]].
79
80 === Apache front-end server ===
81
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]].
83
84 == NotSerializableException ==
85
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]].
87
88 == SEVERE: Error listenerStart ==
89
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]].
91
92 == Parameter count exceeded allowed maximum ==
93
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]].
95
96 == ThreadLocal Errors ==
97
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]].
99
100 == Request header is too large ==
101
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]].
103
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+
121 * Tomcat 7 is not using URF-8 by default. Edit the ##conf/server.xml## file to set the UTF-8 encoding:(((
122 {{code language="none"}}
123 <Connector port="8080"
124 ...
125 URIEncoding="UTF-8">
126 </Connector>
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