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-upgrade2. 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 upgrade3. Install XWiki & Tomcat 10
apt install xwiki-tomcat10-mariadb4. Verify Database Connection
Check if MariaDB is running and accessible:
systemctl status mariadb
mysql -u root5. 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.xmlaccordingly (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"
