Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Installation Steps =
6
7 * 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##//.
8 * 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.
9 * Edit your //conf/server.xml// to set UTF-8 encoding: {{code}}<Connector port="8080" ... URIEncoding="UTF-8"/>{{/code}}
10 * Make sure you [[give enough memory to Java>>#HOutOfMemoryError]]
11
12 == Activate headless mode ==
13
14 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:
15
16 * //Exception: Could not initialize class sun.awt.X11.XToolkit//
17 * //java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable//
18
19 * On Linux create a file ##///TOMCAT_HOME///bin/setenv.sh## and insert the following code:
20 {{code}}#!/bin/sh
21 export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"{{/code}}.
22 * On Windows create a file ##///TOMCAT_HOME///bin/setenv.bat## and insert the following code:
23 {{code}}set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true{{/code}}.
24 * 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.
25
26 == Optional configuration ==
27
28 * 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}}
29 * 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.
30 * 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.
31
32 == Policy configuration ==
33
34 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 :
35
36 {{code}}
37 grant codeBase "file:${catalina.base}/webapps/xwiki/WEB-INF/lib/-" {
38 // for mySQL connection
39 permission java.net.SocketPermission "127.0.0.1:3306", "connect,resolve";
40
41 // XWiki must have access to all properties in read/write
42 permission java.util.PropertyPermission "*", "read, write";
43
44 // Generic detected permissions
45 permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
46 permission java.lang.RuntimePermission "createClassLoader";
47 permission java.lang.RuntimePermission "setContextClassLoader";
48 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.loader";
49 permission java.lang.RuntimePermission "accessDeclaredMembers";
50 permission java.lang.RuntimePermission "getenv.ProgramFiles";
51 permission java.lang.RuntimePermission "getenv.APPDATA";
52 permission java.lang.RuntimePermission "accessClassInPackage.sun.reflect";
53 permission java.lang.RuntimePermission "getClassLoader";
54 permission java.lang.RuntimePermission "accessClassInPackage.org.apache.catalina.connector";
55 permission java.lang.RuntimePermission "reflectionFactoryAccess";
56 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.interceptor";
57 permission java.lang.RuntimePermission "accessClassInPackage.com.sun.jmx.mbeanserver";
58 permission java.lang.RuntimePermission "modifyThread";
59 permission java.lang.RuntimePermission "getProtectionDomain";
60
61 // JAXB permissions
62 permission javax.xml.bind.JAXBPermission "setDatatypeConverter";
63
64 // Serialization related permissions
65 permission java.io.SerializablePermission "allowSerializationReflection";
66 permission java.io.SerializablePermission "creator";
67 permission java.io.SerializablePermission "enableSubclassImplementation";
68
69 // Internal resources access permissions
70 permission java.io.FilePermission "synonyms.txt", "read";
71 permission java.io.FilePermission "lang/synonyms_en.txt", "read";
72 permission java.io.FilePermission "quartz.properties", "read";
73 permission java.io.FilePermission "/templates/-", "read";
74 permission java.io.FilePermission "/skins/-", "read";
75 permission java.io.FilePermission "/resources/-", "read";
76
77 // MBean related permissions
78 permission javax.management.MBeanServerPermission "createMBeanServer";
79 permission javax.management.MBeanPermission "*", "registerMBean";
80 permission javax.management.MBeanPermission "*", "unregisterMBean";
81 permission javax.management.MBeanTrustPermission "register";
82 permission javax.management.MBeanPermission "-#-[-]", "queryNames";
83 permission javax.management.MBeanServerPermission "findMBeanServer";
84
85 // LibreOffice/OpenOffice related permissions
86 permission java.io.FilePermission "/opt/openoffice.org3/program/soffice.bin", "read";
87 permission java.io.FilePermission "/opt/libreoffice/program/soffice.bin", "read";
88 permission java.io.FilePermission "/usr/lib/openoffice/program/soffice.bin", "read";
89 permission java.io.FilePermission "/usr/lib/libreoffice/program/soffice.bin", "read";
90
91 // Allow file storage directory reading - for directory and everything underneath
92 // This is dependent on the setting of environment.permanentDirectory in xwiki.properties
93 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}", "read,write,delete";
94 permission java.io.FilePermission "${catalina.base}${file.separator}xwikidata${file.separator}-", "read,write,delete";
95
96 // Allow file storage directory reading - temporary directory and everything underneath
97 // This is dependent on the setting of environment.temporaryDirectory in xwiki.properties.
98 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}", "read,write,delete";
99 permission java.io.FilePermission "${catalina.base}${file.separator}temp${file.separator}-", "read,write,delete";
100 };
101 {{/code}}
102
103 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.
104
105 === Nginx proxying for Tomcat applications ===
106
107 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.
108
109 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:
110
111 * create this file ##/etc/nginx/conf.d/tomcat.conf##
112 * put the following code inside:(((
113 {{code}}
114 server {
115 listen 80;
116 server_name mydomain.com;
117 # Root to the XWiki application
118 root opt/tomcat/webapps/xwiki;
119
120 location / {
121 #All "root" requests will have /xwiki appended AND redirected to mydomain.com again
122 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
123 }
124
125 location ^~ /xwiki {
126 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
127 proxy_pass http://localhost:8080/xwiki;
128
129 }
130 }
131 {{/code}}
132 )))
133 * restart nginx
134
135 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"]].
136
137 = Troubleshooting =
138
139 == Out Of Memory Error ==
140
141 When you run XWiki in Tomcat with the default settings, you may get an ##Out Of Memory## error (##java.lang.OutOfMemoryError: Java heap space## or ##java.lang.OutOfMemoryError: PermGen space##), especially if you're trying to import large files into your wiki. To solve this allocate more memory to the JVM. For Tomcat this can be done by setting the ##JAVA_OPTS## environment property (to allocate 1GB you would set ##JAVA_OPTS## to ##-Xmx1g##). Another important option is the ##MaxPermSize## parameter. Example: ##-XX:MaxPermSize=512m## allocates 512MB of permanent memory.
142
143 Memory recommendations are available in the [[Performance guide>>platform:AdminGuide.Performances#HMemory]].
144
145 On most Linux distributions, setting the Java memory can be done in ##/etc/tomcat//X///tomcat//X//.conf## or ##/etc/conf.d/tomcat//X//.conf## (where //X// is the version of Tomcat installed):
146
147 {{code language="none"}}
148 JAVA_OPTS="${JAVA_OPTS} -Xmx800m -XX:MaxPermSize=192m"
149 {{/code}}
150
151 On Windows, if you are running Tomcat as a service then defining ##JAVA_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.
152
153 == Java Security Manager ==
154
155 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
156
157 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:
158
159 {{code}}
160 # Use the Java security manager? (yes/no)
161 TOMCAT5_SECURITY=
162 {{/code}}
163
164 Set it to ##no## to turn off the Security Manager.
165
166 == Allowing "/" in page names ==
167
168 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.
169
170 You can configure Tomcat to allow this, by enabling :
171
172 {{code}}
173 org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
174 {{/code}}
175
176 == SEVERE: Error listenerStart ==
177
178 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 this involves copying the following content in a ##WEB-INF/classes/logging.properties## file:
179
180 {{code}}
181 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
182 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
183 {{/code}}

Get Connected