Download and install Tomcat (XWiki requires a Tomcat version >= 7 since it requires Servlet 3.0+). There are plenty of ways to install Tomcat, refer to the Tomcat site for more information. Let's call TOMCAT_HOME the directory where it's installed.

NOTE - if you have issues with maximum cache size - In your $CATALINA_BASE/conf/context.xml add the following content before </Context>:

<Resources cachingAllowed="true" cacheMaxSize="100000" />

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 the following code:

#!/bin/shexportJAVA_OPTS="${JAVA_OPTS} -Djava.awt.headless=true"

On Windows create a file /TOMCAT_HOME/bin/setenv.bat and insert the following code:

set JAVA_OPTS=%JAVA_OPTS% -Djava.awt.headless=true

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.

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 a Tomcat Java Server as a UNIX Daemon - JSVC. Just follow these 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.

Policy configuration

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 :

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.

Using Nginx as a reverse-proxy for Tomcat (http/https)

For a variety of reasons, it is not ideal to allow users to connect directly to tomcat. A popular choice for a reverse-proxy web server is Nginx. These instructions will walk through a very basic deployment of nginx acting as a reverse-proxy for the tomcat XWiki application.

After a typical XWiki installation XWiki will be running on http://localhost:8080/xwiki. Ultimately we will want to access XWiki via http://mydomain.com on a standard http (80) or https (443) port. To accomplish this for unsecure http traffic, the following basic config file gets us started.

http (unsecure)

create this file /etc/nginx/conf.d/tomcat.conf

put the following code inside:

server { listen 80; server_name mydomain.com;

# Normally root should not be accessed, however, root should not serve files that might compromise the security of your server. root /var/www/html;

https (secure)

The following config assumes you are using LetsEncrypt and that your XWiki is hosted on http://localhost:8080/. This config will redirect all unsecure requests to https:// and set the correct proxy headers for a secure nginx+tomcat setup.

First, you will need to add the following config to tomcat's server.xml (located at /etc/tomcat8/server.xml on Ubuntu 16.04). The first line should already be in the file, I include it to give you something to search for (that line is located on line 108 in the Ubuntu 16.04 tomcat8 package). This will help tomcat find your proxy headers.

For more background on this config, see the discussion on this ticket: XWIKI-13963.

Proxying and tunnels

This proxy methods brings remote connections to local connection. This is complementary to SSH-tunneling which is easily done on port 8080 and can be used to test development servers.

For example, if you are running an XWiki on port 80 on your laptop while running the NGinx (or Apache) on a server where it is accessible as https://wiki.yourdomain.com, you can make your XWiki acessible with this URL:

First make sure that the port 8080 is not in use: You can proof this with ssh server wget -O - https://127.0.0.1:8080/ which should display the error message Connection refused. If not, something is running there and it should be stopped.

You can then create the tunnel with the following ssh -R8080:127.0.0.1:8080 server. This tells the server that incoming ("R"emote) connections on port 8080 on the server are to be tunnelled to the local (laptop) port 8080. This method has the advantage that the laptop (typically using a dynamic address) invokes the SSH where as a proxy configured on the server to proxy to the laptop would need to know the address of the laptop.

Configuring tomcat for https

Although allowing users to directly connect to tomcat is not recommended, for a variety of reasons it may be desirable to configure tomcat to serve pages over an https connection.

If using HTTPS for accessing XWiki, several modifications have to be made to ensure proper 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.)

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!

Troubleshooting

Out Of Memory Error

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. You'll need to allocate more memory to the JVM.

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). For example:

CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=192m"

On most Linux distributions, this can also be achieved in /etc/tomcatX/tomcatX.conf or /etc/conf.d/tomcatX.conf (where X is the version of Tomcat installed).

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.

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 code:

# Use the Java security manager? (yes/no)TOMCAT5_SECURITY=

Set it to no to turn off the Security Manager.

Allowing "/" and "\" in page names

Tomcat completely freaks out when there's a %2F or %5C in URLs and it's not something that can be changed in XWiki. See this note for more information.

You can configure Tomcat to allow "/", by setting the org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH system property to true, as in:

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

And by setting the org.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH system property to true to allow "\", as in:

-Dorg.apache.catalina.connector.CoyoteAdapter.ALLOW_BACKSLASH=true

To have both properties permanently enabled on your Tomcat instance, add the lines below to your CATALINA_OPTS environment variable. How to achieve this depends on your operating system, Tomcat distribution and single/multi-instance setup.

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.

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/7.x this involves copying the following content in a WEB-INF/classes/logging.properties file: