Steps

To install and configure Tomcat as your servlet container for XWiki:

1. Download a supported version of Tomcat and the correct version of Tomcat based on your XWiki version:
   • XWiki 12.x–16.x: Tomcat 8 or 9 (avoid 9.0.70)
   • XWiki 17.x and above: Tomcat 10
2. Extract Tomcat to a directory of your choice, referred to as TOMCAT_HOME.
3. Make sure you give enough memory to Java, since by default Tomcat is not configured with enough memory for XWiki.
4. Download the WAR file for the version you need.
5. Extract the XWiki WAR file into a directory named xwiki inside TOMCAT_HOME/webapps/.
6. Create a directory to store XWiki's permanent data (attachments, configurations, extensions).
7. Open TOMCAT_HOME/webapps/xwiki/WEB-INF/xwiki.properties and set the permanent directory path:

    environment.permanentDirectory=TOMCAT_HOME/xwiki-data/ 

8. Configure Tomcat to use UTF-8 as the default encoding by adding the following JVM parameter to the Tomcat startup configuration. (This is generally set by default on Linux packages of Tomcat).

   -Dfile.encoding=utf8

9. Start Tomcat using the method corresponding to your installation type:
   • Manual installation:
     • Linux/Mac: TOMCAT_HOME/bin/startup.sh
     • Windows: TOMCAT_HOME\bin\startup.bat
   • Service installation (for production environments):
     • Linux (systemd): systemctl start tomcat
     • Windows Service: net start Tomcat
10. Open a browser and navigate to: http://localhost:8080/xwiki/bin/view/Main/

FAQ

Why does XWiki show a 500 error about a missing JDBC driver?

The WAR file does not include a database driver.  The next step to get XWiki working with the WAR file is to configure manually a database for XWiki (manually place JAR into TOMCAT_HOME/webapps/xwiki/WEB-INF/lib/ ). If you don't need XWiki for production environments,  you may download the demo package that contains the HSQLDB (which includes the driver).

Why should I set UTF-8 as the default encoding for Tomcat?

To avoid encoding-related issues in XWiki and its extensions (e.g. database drivers or connectors).

Should I enable Java headless mode for Tomcat?

If your Apache Tomcat instance runs on a server without graphical libraries, you should activate headless mode on Apache Tomcat.

What if I have issues with the maximum cache size?

If you have issues with maximum cache size, in your TOMCAT_HOME/webapps/xwiki/META-INF update the following content: <Resources cacheMaxSize="100176" />.

How can I modify the port 8080?

To modify the port on which Tomcat will run, search in server.xml for all instances of 8080 (in Linux this can also be 8180) and replace this with the port value you wish to use.

Should Tomcat run as a UNIX daemon using JSVC?

The only reason to make Tomcat a daemon is to make it runnable on port 80, which can be replaced by using a proxy server (such as NginX or Apache) on port 80 and then forwarding to Tomcat on port 8080. 

More

To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.

Related

• Servlet Container Support Strategy.
• Set up NginX Proxy Server.
• Configure Apache HTTP Server as a Proxy on a Linux Os or Configure Apache HTTP Server as a Proxy on a Windows Os.
• Configure Tomcat for XWiki in Docker.