Upgrading Tomcat

Introduction

When your web application is up and running, sooner or later, the need will come to upgrade Tomcat, for example for security reasons.

You probably want to make this change without end users even noticing. It is then an advantage if we can keep the Tomcat home location, port number which tomcat runs on etc. This is is a proposed way to achieve that kind of upgrade.

N.B. The guide below is only for upgrading within the same major version of Tomcat, for example: From 9.0.17 to 9.0.98. If you go e.g. from Tomcat 9 to Tomcat 10, you should not keep configuration files as they are, but rather try to merge them into default configuration files of Tomcat 10.

The syntax below is for Windows. If you are on Linux you can surely easily adapt it!

Step-by-Step Guide

1. Download the target Tomcat version from the Apache Tomcat download site. Put the downloaded zip in the …\Corzia\Downloads folder.

2. Extract all files from the zip file.

3. Let’s assume the existing Tomcat is in a folder called tdk8080 and that your extracted folder name is apache-tomcat-9.0.98-windows-x64. Inside this folder there will be folder named apache-tomcat-9.0.98. Move the folder apache-tomcat-9.0.98 into the …\Corzia\Apache\ folder and rename it tdk8080new.

4. Now copy the conf folder from tdk8080 to tdk8080new (replacing existing files). Also copy the webapps folder from tdk8080 to tdk8080new (replacing existing files). Check if there is any other folder that exists in the old Tomcat but not in the new one that might make sense to copy (for example a Cert folder containing SSL certificates).

5. In the …\tdk8080new\bin folder, rename the application files Tomcat9 and Tomcat9w to Tomcat98080 and Tomcat98080w, respectively (or whatever names they have in the old Tomcat installation). 

6. If Tomcat runs as a service with a particular user account, make sure this user account has as good access permissions to tdk8080new as it has to tdk8080.

7. Stop the Tomcat service. Make sure it goes to the Stopped state (that's when ”Start” button becomes enabled). Then close the 'Tomcat properties' dialogue (if open).

8. Rename the folder …\Corzia\Apache\tdk8080 to …\Corzia\Apache\tdk8080old. and rename the folder …\Corzia\Apache\tdk8080new to …\Corzia\Apache\tdk8080.

9. The renaming should not affect shortcuts referring to renamed folders but just to be sure, check that your shortcuts (in the ...\Corzia\Tomcat 8080 folder) are not pointing to old Tomcat folder name.

10. Now use your updated shortcut to open 'Tomcat Properties'. Review the launch arguments of Tomcat, perform any desired updates both in 'Tomcat properties' and in the corresponding page for Tomcat server properties in Eclipse.

11. Change the Description of Tomcat in 'Tomcat properties' to match the target release of Tomcat upgrade.

12. If this Tomcat installation is a back end service receiving requests over AJP from a web front end (or simply there is an AJP connector defined in server.xml), and the old Tomcat version was 9.0.30 or earlier, you need to edit the server.xml file in the conf folder. Make sure the AJP connector tag is not commented out and that it contains the address and secretRequired attributes. Like this, for example:

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" address="0.0.0.0" secretRequired="false"/>

N.B.: secretRequired=”false” is not suitable if the front end and back end servers are on different networks or on an untrusted network - then you need to set the secret up on both front end and back end (ask ChatGPT for details).

13. Start the Tomcat service. Check stdout and stderr log files for error messages after start-up.

14. If you changed any configuration on the front end web server in step 12 above, re-start the front end Tomcat service (or the entire web server).

15. Log in and check that applications look healthy.

If you run into problems that you cannot solve quickly, just rename the folders (and the Tomcat Properties shortcut) back to their previous names  - and you are back at where you started.