Apache Tomcat should be kept up to date so that the server continues to receive security fixes. Tomcat releases new patch versions regularly, and applying them is a routine maintenance task rather than an iGene upgrade.
This page covers updating an existing installation. For setting Tomcat up on a new server, see Installing Tomcat.
This guide installs the new version into a new folder alongside the existing one. That takes a little longer than replacing files in place, but it means the working installation is untouched and rolling back is simply a matter of pointing the service back at it.
Stay on the same major version of Tomcat unless Genial has advised otherwise. iGene runs on Tomcat 9, so an existing installation should be updated to a newer Tomcat 9 release, not to Tomcat 10 or 11.
If the service on this server has a different name. This page uses iGene, which is the name new installations are given. Servers built before this naming standard will have a service called Tomcat9, and their configuration tool will be tomcat9w.exe rather than iGenew.exe. Check the name in Services and use it consistently in place of iGene throughout this page, including when the service is reinstalled. A Tomcat update is not the time to change a service name.
Open a command prompt and run:
C:\path\to\tomcat\bin\version.bat
Make a note of the version reported.
Open the service configuration tool:
C:\path\to\tomcat\bin\iGenew.exe
Take a screenshot of each tab, paying particular attention to:
Do not skip this step. These settings are stored against the Windows service, not in the Tomcat folder, so they are lost when the service is reinstalled and have to be entered again by hand.
Because the new version goes into a separate folder, the existing Tomcat installation is left intact and is itself the rollback. There is no need to take a separate copy of it.
Everything that is copied out of it during this update is read only, so the old folder still contains a complete, working Tomcat with iGene in it and all of its configuration.
Do not delete, move or rename the old Tomcat folder until the update has been validated. It is the only thing standing between a failed update and a rebuild.
The one part of the old installation that is not protected this way is the Windows service configuration, because those settings are held against the service rather than in the folder. That is what the screenshots above are for.
A database backup is not required for a Tomcat update, because nothing in the database changes. Take one anyway if your local change process calls for it.
Download the latest Apache Tomcat 9 release, using the ZIP distribution.
Download from: https://tomcat.apache.org/download-90.cgi
Extract the download to a new folder alongside the existing installation, naming the folder after the version you are installing:
C:\path\to\apache-tomcat-9.0.122
The ZIP already contains a folder named this way, so extracting it into the folder that holds the current installation will normally produce the right name without you doing anything.
Do not extract it over the top of the existing folder.
Use the real version number rather than a name like tomcat-new or tomcat-latest. This update leaves the previous installation on the server, and the next one will leave this installation on the server, so within a couple of updates a folder called “new” will be two versions out of date and nobody will be able to tell which is which. Version numbers stay true and make it obvious what can eventually be removed.
The rest of this page uses C:\path\to\apache-tomcat-9.0.122 to mean the new installation and C:\path\to\tomcat to mean the existing one. Substitute your own paths.
net stop iGene
Alternatively, open Services, find the iGene service and stop it there. Wait until it has fully stopped before continuing.
Copy the following from the old installation into the new one.
Copy the application into the new webapps folder:
webapps\ROOT.war
There is no need to copy webapps\ROOT\. Tomcat recreates that folder automatically when the application starts.
This one is essential. iGene is told where its home folder is by a Tomcat context file:
conf\Catalina\localhost\ROOT.xml
It contains a single parameter pointing at the iGene home folder, and looks like this:
<Context>
<Parameter name="igene_home" value="D:\igene_home" override="true" />
</Context>
Copy this file into the same location under the new installation, creating the Catalina\localhost folders if they do not already exist.
If this file is missing, iGene will not be able to find its home folder and will not start correctly. It is easy to overlook because it sits three folders down inside conf rather than alongside the other configuration files.
Copy across any other files that were customised for this installation, typically:
conf\server.xml if ports, connectors or the shutdown port were changedconf\context.xml if it was edited for this installationbin\setenv.bat if one was created for this installationCopy only the files you know were customised, and keep the new version’s copies of everything else. If you are not sure which files were changed, contact Genial before continuing rather than copying the whole conf folder across.
Open a Command Prompt as Administrator and run, using the service name you recorded earlier:
C:\path\to\tomcat\bin\service.bat remove iGene
Always remove the service this way rather than with sc delete. If the service was installed under a custom name, Tomcat renamed its own executables to match, and only service.bat remove puts them back. Using sc delete leaves the renamed executables behind and the next installation will not behave as expected.
If CATALINA_HOME or CATALINA_BASE are set on this server, update them to point at the new folder before installing the service below, otherwise the new service installs against the old paths:
CATALINA_HOME=C:\path\to\apache-tomcat-9.0.122
CATALINA_BASE=C:\path\to\apache-tomcat-9.0.122
Still in the Administrator Command Prompt, run:
C:\path\to\apache-tomcat-9.0.122\bin\service.bat install iGene --rename
Install the service under the same name it had before. service.bat install without a name always creates a service called Tomcat9, so if you leave the name off, or use a different one, the server ends up with a service under the wrong name and anything that referred to the old one stops working. On a server where the service was called Tomcat9, use service.bat install Tomcat9 and leave --rename off.
Open the service configuration tool from the new folder:
C:\path\to\apache-tomcat-9.0.122\bin\iGenew.exe
Using the screenshots you took earlier, re-enter:
Click Apply, then OK.
net start iGene
Allow sufficient time for iGene to deploy and start.
Confirm Tomcat is responding:
http://<server>:8080
Open iGene in a web browser.
Log in with a valid user account.
Carry out a quick functional check to confirm the application is operating correctly.
Confirm the new version is running:
C:\path\to\apache-tomcat-9.0.122\bin\version.bat
Because the previous installation is still on disk and untouched, rolling back means pointing the service back at it:
Open an Administrator Command Prompt and remove the new service:
C:\path\to\apache-tomcat-9.0.122\bin\service.bat remove iGene
If CATALINA_HOME or CATALINA_BASE were changed during the update, set them back to the old folder now, before reinstalling, otherwise the reinstalled service picks up the new paths.
Reinstall the service from the old folder, using the original service name:
C:\path\to\tomcat\bin\service.bat install iGene --rename
Re-apply the service settings from your screenshots.
Start the service and confirm iGene is operating correctly.
The old Tomcat folder is your rollback, so keep it until you are confident the update has held. Once the new version has been running without problems for an agreed period, it can be deleted. Keeping it until the next maintenance window is a reasonable precaution.