Tomcat Installation
Installation Steps
- Download and install Tomcat. It's usually as simple as unzipping it in a directory. Let's call this directory TOMCAT_HOME.
- Extract the XWiki WAR 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.
- Edit your conf/server.xml to set UTF-8 encoding: <Connector port="8080" ... URIEncoding="UTF-8"/>
Activate headless mode
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:
- Exception: Could not initialize class sun.awt.X11.XToolkit
- java.lang.InternalError: Can't connect to X11 window server using 'localhost:10.0' as the value of the DISPLAY variable
- On Linux create a file /TOMCAT_HOME/bin/setenv.sh and insert text
#!/bin/sh
export JAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true". - On Windows create a file /TOMCAT_HOME/bin/setenv.bat and insert text
set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true. - When running as 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.
Optional configuration
- Edit your conf/server.xml to enable gzip compression: <Connector port="8080" ... compression="on" compressionMinSize="2048" compressableMimeType="text/html,text/xml,text/css,text/javascript,application/x-javascript"/>
- 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.
- It is possible to setup Tomcat Java Server as a UNIX Daemon - JSVC. Just follow this instructions. 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.
Nginx proxying for Tomcat applications
As Tomcat is not a true web server, it's worth to use it as backend. Nginx is one of the best solutions for the frontend web server.
So, after typical XWiki installation we have XWiki running on http://localhost:8080/xwiki. Most probably, we want access XWiki via http://mydomain.com on standard 80 port. Tuning Nginx will give us desired result:
- create file /etc/nginx/conf.d/tomcat.conf
- put following code inside:server {
listen 80;
server_name mydomain.com;
# Root to the XWiki application
root opt/tomcat/webapps/xwiki;
location / {
#All "root" requests will have /xwiki appended AND redirected to mydomain.com again
rewrite ^ $scheme://$server_name/xwiki$request_uri? permanent;
}
location ^~ /xwiki {
# If path starts with /xwiki - then redirect to backend: XWiki application in Tomcat
proxy_pass http://localhost:8080/xwiki;
}
} - restart nginx
Now all http://mydomain.com/* requests will lead to XWiki application. Please note, that these settings are basic, for more flexible solutions refer to Nginx documentation.
Troubleshooting
Out Of Memory Error
When you later run XWiki in Tomcat you may get an Out Of Memory error, 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 (on Windows to allocate 300MB you would set JAVA_OPTS to -Xmx300m). Another important option is the MaxPermSize parameter. Example: -XX:MaxPermSize=1g allocates 1GB of Permanent memory. If you are running Tomcat as service then defining JAVA_OPTS will not help. There is a 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.
Java Security Manager
By default Tomcat is configured to have the Java Security Manager turned on. See the sample policy file for more details.
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 in the file:
TOMCAT5_SECURITY=
Set it to no to turn off the Security Manager.
Allowing "/" in page names
Tomcat completely freaks out when there's a %2F in URLs, and it's not something that can be changed in XWik, see:
http://tomcat.apache.org/security-6.html#Fixed_in_Apache_Tomcat_6.0.10
You can configure Tomcat to allow this, by enabling :
SEVERE: Error listenerStart
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:
org.apache.catalina.core.ContainerBase.[Catalina].handlers = java.util.logging.ConsoleHandler