Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Installation Steps =
6
7 {{error}}
8 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>>http://jira.xwiki.org/browse/XWIKI-13556]] for some versions of Tomcat. Thus you should **not** use the following Tomcat versions:
9 * >= 9.0.0.M5 and < 9.0.0.M10 for the 9.0.x branch (fixed in 9.0.0.M10)
10 * >= 8.5.1 and < 8.5.5 for the 8.5.x branch (fixed in 8.5.5)
11 * >= 8.0.34 and < 8.0.37 for the 8.0.x branch (fixed in 8.0.37)
12 * >= 7.0.70 and < 7.0.71 for the 7.0.x branch (fixed in 7.0.71)
13 {{/error}}
14
15 * Download and install [[Tomcat>>http://tomcat.apache.org/]]. It's usually as simple as unzipping it in a directory. Let's call this directory //##TOMCAT_HOME##//.
16 * Extract the [[XWiki WAR>>xwiki:Main.Download]] into a directory named ##xwiki## in ##//TOMCAT_HOME///webapps/##. The reason you're expanding the WAR is because you'll need to modify one configuration file from inside the WAR later on when you configure the database access.
17 * Edit your //conf/server.xml// to set UTF-8 encoding: {{code}}<Connector port="8080" ... URIEncoding="UTF-8"/>{{/code}}
18 * Make sure you [[give enough memory to Java>>#HOutOfMemoryError]] since by default Tomcat is configured with not enough memory for XWiki.
19
20 == Activate headless mode ==
21
22 If you're operating XWiki on a Linux server with no X11 libraries installed you have to enable headless mode for your Tomcat installation. Sometimes this is also needed on Windows platforms. Typical exceptions are:
23
24 * ##Exception: Could not initialize class sun.awt.X11.XToolkit##
25 * ##java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable##
26
27 * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:(((
28 {{code}}
29 #!/bin/sh
30 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"
31 {{/code}}
32 )))
33 * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:(((
34 {{code}}
35 set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true
36 {{/code}}
37 )))
38 * When running as a Windows service the ##setenv.bat## is not working. See registry ##HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun 2.0\//FOOBAR//\Parameters\Java## for similar settings.
39
40 == Optional configuration ==
41
42 * Edit your ##conf/server.xml## to enable gzip compression: {{code}}<Connector port="8080" ... compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"/>{{/code}}
43 * If you want to modify the port on which Tomcat will run, edit ##//TOMCAT_HOME///conf/server.xml/##. Search for ##8080## (sometimes ##8180## if you are under Linux) and replace with the port value you wish to use.
44 * It is possible to setup a Tomcat Java Server as a UNIX Daemon - JSVC. Just follow [[these instructions>>http://www.malisphoto.com/tips/tomcatonosx.html?#Anchor-JSVC||target="new"]]. The only reason to make Tomcat a daemon is to make it runnable on the 80th port, which can be replaced by using NginX as a proxy on the 80th port and then forwarding to Tomcat to the 8080th port.
45
46 == Policy configuration ==
47
48 For those who activate the security manager for Tomcat, add this portion of code to the end of your ##conf/catalina.policy## file from your Tomcat installation. You can adapt the code for the available installations of OpenOffice/LibreOffice on your server and for different databases :
49
50 {{code}}
51 grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {
52 // for mySQL connection
53 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
54
55 // XWiki must have access to all properties in read/write
56 permission java.util.PropertyPermission "*", "read, write";
57
58 // Generic detected permissions
59 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
60 permission java.lang.RuntimePermission "createClassLoader";
61 permission java.lang.RuntimePermission "setContextClassLoader";
62 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";
63 permission java.lang.RuntimePermission "accessDeclaredMembers";
64 permission java.lang.RuntimePermission "getenv.ProgramFiles";
65 permission java.lang.RuntimePermission "getenv.APPDATA";
66 permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";
67 permission java.lang.RuntimePermission "getClassLoader";
68 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";
69 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.tomcat.util.threads";
70 permission java.lang.RuntimePermission "reflectionFactoryAccess";
71 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";
72 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";
73 permission java.lang.RuntimePermission "modifyThread";
74 permission java.lang.RuntimePermission "getProtectionDomain";
75
76 // JAXB permissions
77 permission javax.xml.bind.JAXBPermission "setDatatypeConverter";
78
79 // Serialization related permissions
80 permission java.io.SerializablePermission "allowSerializationReflection";
81 permission java.io.SerializablePermission "creator";
82 permission java.io.SerializablePermission "enableSubclassImplementation";
83
84 // Internal resources access permissions
85 permission java.io.FilePermission "synonyms.txt", "read";
86 permission java.io.FilePermission "lang/synonyms_en.txt", "read";
87 permission java.io.FilePermission "quartz.properties", "read";
88 permission java.io.FilePermission "/templates/-", "read";
89 permission java.io.FilePermission "/skins/-", "read";
90 permission java.io.FilePermission "/resources/-", "read";
91
92 // MBean related permissions
93 permission javax.management.MBeanServerPermission "createMBeanServer";
94 permission javax.management.MBeanPermission "*", "registerMBean";
95 permission javax.management.MBeanPermission "*", "unregisterMBean";
96 permission javax.management.MBeanTrustPermission "register";
97 permission javax.management.MBeanPermission "-#-[-]", "queryNames";
98 permission javax.management.MBeanServerPermission "findMBeanServer";
99
100 // LibreOffice/OpenOffice related permissions
101 permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";
102 permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";
103 permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";
104 permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";
105
106 // Allow file storage directory reading - for directory and everything underneath
107 // This is dependent on the setting of environment.permanentDirectory in xwiki.properties
108 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";
109 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";
110
111 // Allow file storage directory reading - temporary directory and everything underneath
112 // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
113 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";
114 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";
115 };
116 {{/code}}
117
118 Please note that this policy configuration file have been tested on CentOS 5.9 with Sun JDK 1.7.0u21 on Tomcat 7.0.40 with XWiki 5.0.1 installed.
119
120 == Nginx proxying for Tomcat applications ==
121
122 As Tomcat is not a true web server, it's worth to use it as backend. [[Nginx>>http://wiki.nginx.org/Main||rel="__blank"]] is one of the best solutions for the frontend web server.
123
124 So, after a typical XWiki installation we have XWiki running on ##http:~/~/localhost:8080/xwiki##. Most probably, we want to access XWiki via ##http:~/~/mydomain.com## on standard 80 port. Tuning Nginx will give us the desired result:
125
126 * create this file ##/etc/nginx/conf.d/tomcat.conf##
127 * put the following code inside:(((
128 {{code}}
129 server {
130 listen 80;
131 server_name mydomain.com;
132 # Root to the XWiki application
133 root /opt/tomcat/webapps/xwiki;
134
135 location / {
136 #All "root" requests will have /xwiki appended AND redirected to mydomain.com again
137 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
138 }
139
140 location ^~ /xwiki {
141 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
142 # Read more about proxy_pass: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
143 proxy_pass http://localhost:8080;
144 proxy_set_header X-Real-IP $remote_addr;
145 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
146 proxy_set_header Host $http_host;
147 proxy_set_header X-Forwarded-Proto $scheme;
148 }
149 }
150 {{/code}}
151 )))
152 * restart nginx
153
154 Now all ##http:~/~/mydomain.com/*## requests will lead to the XWiki application. Please note that these settings are basic. For more flexible solutions please refer to [[the Nginx documentation>>http://wiki.nginx.org/Main||rel="__blank"]].
155
156 == HTTPS setting ==
157
158 * If using HTTPS for accessing XWiki, several modifications have to be made to ensure flawless functionality. Since urls are generated from relative path (##/xwiki/bin/show/Space/Page##), Tomcat has to know which protocol to use, otherwise JSON requests with redirect fails (attachment uploads, extension updating, etc.)
159 * Modify connector (in ##server.xml##) to {{code}}<Connector port="8080" ... secure="true" scheme="https" />{{/code}}
160 * Modify host (in ##server.xml##) and add Remote Ip Valve {{code}}<Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="x-forwarded-for" protocolHeader="x-forwarded-proto" />{{/code}} (only needed if using another server for HTTPS)
161
162 {{info}}
163 If using another server as a HTTPS proxy (such as Nginx or Apache httpd), ##X-Forwarded-For## and ##X-Forwarded-Proto## headers have to be set!
164 {{/info}}
165
166 = Troubleshooting =
167
168 == Out Of Memory Error ==
169
170 When you run XWiki in Tomcat with the default settings, you'll probably get an ##Out Of Memory## error (##java.lang.OutOfMemoryError: Java heap space## or ##java.lang.OutOfMemoryError: PermGen space##) since the default Tomcat memory settings are not enough for [[XWiki Memory Requirements>>platform:AdminGuide.Performances#HMemory]]. You'll need to allocate more memory to the JVM.
171
172 One easy solution to configure Tomcat's memory is to create a ##setenv.sh## file (or ##setenv.bat## on Windows) in ##[TOMCAT_HOME]/bin/## (where ##[TOMCAT_HOME]## is where you've installed Tomcat) and inside this file add the following (adjust the memory values according to the [[XWiki Memory Requirements>>platform:AdminGuide.Performances#HMemory]]). For example:
173
174 {{code language="none"}}
175 CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"
176 {{/code}}
177
178 On most Linux distributions, this can also be achieved in ##/etc/tomcat//X///tomcat//X//.conf## or ##/etc/conf.d/tomcat//X//.conf## (where //X// is the version of Tomcat installed).
179
180 On Windows, if you are running Tomcat as a service then defining ##CATALINA_OPTS## will not help. There is an utility provided in the ##bin## folder of your Tomcat installation (for example for Tomcat 5.x on Windows it's called tomcat5w.exe). It's a GUI tool which can be used to set various options including the heap size.
181
182 == Java Security Manager ==
183
184 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
185
186 If you want to turn off the Java Security Manager for Tomcat, edit the Tomcat startup script. You might also want to check your ##/etc/init.d/tomcat## file or ##/etc/default/tomcat5.5##. You should see the following code:
187
188 {{code}}
189 # Use the Java security manager? (yes/no)
190 TOMCAT5_SECURITY=
191 {{/code}}
192
193 Set it to ##no## to turn off the Security Manager.
194
195 == Allowing "/" in page names ==
196
197 Tomcat completely freaks out when there's a ##%2F## in URLs and it's not something that can be changed in XWiki. See [[this note>>http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10]] for more information.
198
199 You can configure Tomcat to allow this, by enabling :
200
201 {{code}}
202 org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
203 {{/code}}
204
205 Note that if you're using Apache you also need to [[configure Apache to allow encoded / and \>>https://httpd.apache.org/docs/current/mod/core.html#allowencodedslashes]].
206
207 == NotSerializableException ==
208
209 If you get the following:
210
211 {{code}}
212 SEVERE: IOException while loading persisted sessions: java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
213 java.io.WriteAbortedException: writing aborted; java.io.NotSerializableException: org.xwiki.model.internal.reference.LocalStringEntityReferenceSerializer
214 at java.io.ObjectInputStream.readObject0(Unknown Source)
215 at java.io.ObjectInputStream.defaultReadFields(Unknown Source)
216 {{/code}}
217
218 This means that on startup Tomcat tries to load saved Sessions and fails to do so. In this case it fails because some non-serializable object was put in the Servlet Session. To work around the issue [[you can tell Tomcat to not save sessions>>http://dev-answers.blogspot.fr/2007/03/how-to-turn-off-tomcat-session.html]].
219
220 == SEVERE: Error listenerStart ==
221
222 If you get this error in your Tomcat logs then you'll need to enable finer-grained logging configuration to see what's the problem. For Tomcat 6.x/7.x this involves copying the following content in a ##WEB-INF/classes/logging.properties## file:
223
224 {{code}}
225 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
226 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
227 {{/code}}

Get Connected