Show last authors
author | version | line-number | content |
---|---|---|---|
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}} |