Upgrading XWiki to Version 17 on Ubuntu – Including Migration to Tomcat 10

In this post, I document how I successfully upgraded XWiki 16.10 to 17.4, including the switch from Tomcat 9 to Tomcat 10, resolving database connection issues, and ensuring proper operation behind a reverse proxy.

---

✨ Starting Point

• Ubuntu server 22.04 running XWiki 16.10

• Tomcat 9 and MariaDB 10.6 installed

• XWiki operating behind a reverse proxy

• Goal: Upgrade to XWiki 17 with an up-to-date environment and working proxy configuration. As 17 needs tomcat 10 we upgrade to ubuntu server 24.04

---

✅ Step-by-Step Guide

1. Prepare the System

apt update
apt upgrade
reboot
dpkg -l | grep -iE 'mysql|mariadb'
apt remove xwiki-tomcat9-mariadb
apt dist-upgrade
reboot
do-release-upgrade

2. Restore the XWiki Repository

After the release upgrade, the file xwiki-stable.list was moved to .distUpgrade in /etc/apt/sources.list.d/. To restore it:

mv xwiki-stable.list.distUpgrade xwiki-stable.list
apt update
apt upgrade

3. Install XWiki & Tomcat 10

apt install xwiki-tomcat10-mariadb

4. Verify Database Connection

Check if MariaDB is running and accessible:

systemctl status mariadb
mysql -u root

5. Update Hibernate Configuration

Edit /etc/xwiki/hibernate.cfg.xml and set the correct password for the XWiki MariaDB user, as the default password in the configuration does not work.

6. Restart Tomcat 10

systemctl restart tomcat10
systemctl status tomcat10

---

🌟 Running the Upgrade

Important: The URL wiki.mydomain.com did not resolve properly through the proxy. Accessing XWiki via the internal IP of the server was required:

http://10.11.12.1:8080/xwiki
http://10.11.12.1:8080/xwiki/bin/distribution/XWiki/Distribution?xredirect=

There, the upgrade was completed using the Distribution Wizard.

---

🔧 Configuring the Proxy Correctly

To ensure that XWiki runs smoothly behind the reverse proxy:

• Edit /etc/tomcat10/server.xml accordingly (ProxyName, ProxyPort, etc.)

• Optionally, restore the configuration from the previous Tomcat 9 setup or Proxmox backups

Example:

<Connector port="8080" protocol="HTTP/1.1"
           connectionTimeout="20000"
           redirectPort="8443"
           proxyName="wiki.mydomain.com"
           proxyPort="443"
           scheme="https"/>

---

🚀 Conclusion

Upgrading to XWiki 17 and switching to Tomcat 10 on Ubuntu 24.04 can be done cleanly with a bit of patience. Critical elements are:

• Proper Hibernate and proxy configuration

• Ensuring a working MariaDB connection via TCP

• Running the Distribution Wizard via direct IP access if proxy settings are not yet correct

The result is a modern and stable XWiki installation ready for future expansion.

There, the upgrade was completed using the Distribution Wizard.

---

🔧 Optional: Increase RAM Allocation

To allocate more memory to Tomcat, you can add this line in the JAVA_OPTS in /etc/default/tomcat10:

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m"