Tomcat Upgrade Documentation

Question

Overview

Keeping your Tomcat instance up-to-date is critical for maintaining a secure and optimized environment. This document provides comprehensive instructions for upgrading Apache Tomcat 9.

Security Considerations

Regular Tomcat upgrades are essential for addressing security vulnerabilities. For a complete list of vulnerabilities in older Tomcat 9 versions, refer to the official Tomcat security page.

For the supported version of Tomcat with regards to your Jahia version, please refer to supported stack.

Prerequisites

• Backup your environment before proceeding
• Download Tomcat 9.0.99 from Apache Tomcat's official website
• Schedule a maintenance window for the upgrade

Answer

Step-by-Step Instructions

1. Download the new Tomcat version
   • Obtain Tomcat 9.0.99 from official Apache sources
   • Verify the download integrity using checksums if available
2. Shutdown your Jahia server
3. Create a backup
   • Make a copy of your current Tomcat directory
   • Store this backup for restoring libraries and rollback purposes
4. Prepare for installation
   • Rename or move your existing Tomcat folder (e.g., tomcat-old)
5. Install new Tomcat version
   • Extract the Tomcat 9.0.99 archive to the appropriate location
   • Ensure proper ownership and permissions on the new files
6. Restore webapp
   • Copy your existing ROOT or context-folder from the backup's webapps directory to the new Tomcat's webapps directory
7. Restore required libraries
   • From your backup's /tomcat/lib directory, copy the following files to the new installation:

   ccpp-<version>.jar
   pluto-container-api-<version>.jar
   pluto-container-driver-api-<version>.jar
   pluto-taglib-<version>.jar
   portals-bridges-common-<version>.jar
   portlet-api_<version>.jar

8. Restore database libraries
   • From your backup's /tomcat/lib directory, copy the DB driver you need:
     • For Derby: derby-<version>.jar
     • For MySQL: mysql-connector-java-<version>.jar
     • For MariaDB: mariadb-java-client-<version>.jar
     • For SQL Server: mssql-jdbc-<version>.jar
     • For Oracle: ojdbc8-<version>.jar and orai18n-<version>.jar
     • For PostgreSQL: postgresql-<version>.jar
        
9. Restore configuration files
   • Copy /tomcat/conf/server.xml from your backup to the new installation
   • If using AJP, ensure the connector includes the parameter secretRequired="false" if needed
   • Copy /tomcat/conf/catalina.properties from your backup to the new installation
   • Copy any other customized configuration files (web.xml, context.xml, etc.)
      
10. Restore environment settings
    • Copy /tomcat/bin/setenv.sh (for Linux/Unix) or /tomcat/bin/setenv.bat (for Windows) from your backup to the new tomcat
       
11. Start your environment
    • Launch Tomcat and verify basic functionality

Post-Upgrade Tasks

• Verify deployment
  • Check Jahia logs for any errors
  • Monitor system performance after the upgrade
     

Rollback Procedure

If problems occur after the upgrade, follow these steps to revert to the previous Tomcat version:

1. Stop Tomcat
2. Remove or rename the new Tomcat directory
3. Restore the backup Tomcat directory to its original location
4. Start Tomcat

Additional Information

• Always test the upgrade in a non-production environment first
• Keep previous Tomcat versions available for troubleshooting purposes

For assistance with any issues faced during the upgrade, you can reach out to Jahia Support Team.