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 or 11
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. Configure a relational database, since XWiki initializes and attempts to connect to the database as soon as Tomcat auto-deploys the webapp.
7. Create a directory to store XWiki's permanent data (attachments, configurations, extensions).
8. Open TOMCAT_HOME/webapps/xwiki/WEB-INF/xwiki.properties and set the permanent directory path:

    environment.permanentDirectory=TOMCAT_HOME/xwiki-data/ 

9. 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=UTF-8

10. 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
11. 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 package does not include a JDBC driver. Configure a relational database manually and copy the required JAR to TOMCAT_HOME/webapps/xwiki/WEB-INF/lib/. For testing, you can instead use the Demo package, which includes HSQLDB.

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?

Enable Java headless mode if Tomcat runs on a server without a graphical environment.

What if I have issues with the maximum cache size?

Update TOMCAT_HOME/webapps/xwiki/META-INF and set: <Resources cacheMaxSize="100176" />.

How can I modify the port 8080?

Edit server.xml and replace every occurrence of 8080 (or 8180 on some Linux systems) with the desired port.

Should Tomcat run as a UNIX daemon using JSVC?

Usually no. If you need port 80, use a reverse proxy (Nginx or Apache) to forward requests to Tomcat on 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.
• XWiki in Docker.