Wiki source code of Tomcat Installation

Version 18.3 by HoaniCross on 2013/05/27

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 === Nginx proxying for Tomcat applications ===
33
34 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.
35
36 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:
37
38 * create this file ##/etc/nginx/conf.d/tomcat.conf##
39 * put the following code inside:(((
40 {{code}}
41 server {
42 listen 80;
43 server_name mydomain.com;
44 # Root to the XWiki application
45 root opt/tomcat/webapps/xwiki;
46
47 location / {
48 #All "root" requests will have /xwiki appended AND redirected to mydomain.com again
49 rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
50 }
51
52 location ^~ /xwiki {
53 # If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
54 proxy_pass http://localhost:8080/xwiki;
55
56 }
57 }
58 {{/code}}
59 )))
60 * restart nginx
61
62 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"]].
63
64 = Troubleshooting =
65
66 == Out Of Memory Error ==
67
68 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.
69
70 Memory recommendations are available in the [[Performance guide>>platform:AdminGuide.Performances#HMemory]].
71
72 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):
73
74 {{code language="none"}}
75 JAVA_OPTS="${JAVA_OPTS} -Xmx800m -XX:MaxPermSize=192m"
76 {{/code}}
77
78 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.
79
80 == Java Security Manager ==
81
82 By default Tomcat is configured to have the Java Security Manager turned on. See the [[sample policy file>>AdminGuide.InstallationWAR#HInstallandconfigureaServletContainer]] for more details.
83
84 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:
85
86 {{code}}
87 # Use the Java security manager? (yes/no)
88 TOMCAT5_SECURITY=
89 {{/code}}
90
91 Set it to ##no## to turn off the Security Manager.
92
93 == Allowing "/" in page names ==
94
95 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.
96
97 You can configure Tomcat to allow this, by enabling :
98
99 {{code}}
100 org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH
101 {{/code}}
102
103 == SEVERE: Error listenerStart ==
104
105 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:
106
107 {{code}}
108 org.apache.catalina.core.ContainerBase.[Catalina].level = INFO
109 org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler
110 {{/code}}

Get Connected