The Apache Tomcat® software is an open source implementation of the Java Servlet, JavaServer Pages, Java Expression Language and Java WebSocket technologies
1. The tools
- Apache Tomcat 8
- Apache Tomcat 9
2. Introduction
In this tutorial we are going to learn how to upgrade the Tomcat Server 8 to the new Tomcat Server 9.
3. Prerequisites
- Tomcat 8 installed and running
4. JDK 8
To use Tomcat 9 first of all you need to install the JDK 8. To check the JDK Version, do the following command on the console:
Java Version
C:\>java -version
Apache Tomcat 9 supports the Java Servlet 4.0, JavaServer Pages 2.4, Java Unified Expression Language 3.1 and Java API for WebSocket 2.0.
You should get a similar output to this:
Version output
java version "1.8.0_40" Java(TM) SE Runtime Environment (build 1.8.0_40-b25) Java HotSpot(TM) Client VM (build 25.40-b25, mixed mode)
We can also check for the javac version. javac is the primary Java compiler included in the Java Development Kit (JDK). The compiler accepts source code conforming to the Java language specification and produces bytecode conforming to the Java Virtual Machine Specification.
javac version
javac -version
Version output
javac 1.8.0_40
If you don’t have the JDK 8 or the OpenJDK 8 installed, you need to uninstall the previous JDK and install the new JDK to make Tomcat 9 work. You can have multiples JDK installed on the same machine but to make this work, it is necessary to do some additional adjustments.
5. Compatibility
5.1 Servlet 4.0 API
Tomcat 9 supports the new Servlet 4.0 API. The Servlet 4.0 specification brings HTTP/2 to Java EE.
5.2 BIO connector removed
The Java blocking IO implementation has been removed. You need to switch the applications that use BIO to the Java non-blocking IO implementation.
5.3 Comet support removed
If your application uses Comet before you use Tomcat 9 you need to migrate your application to a newer technology like WebSockets.
6. Migrate the configuration
Go to the Apache Tomcat 8 and backup your old configuration files.
You need to check each file for any changes made to them. It’s a good idea to document your changes on your Tomcat Configuration files because every time you make a modification a comment will help you in the future. When you find a change first you need to check if that change is compatible with the new version of Tomcat.
6.1 Migrate the users
One of the most important things is to migrate the users. Open the tomcat-users.xml file:
tomcat-users.xml
<?xml version='1.0' encoding='utf-8'?>
<tomcat-users xmlns="http://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
version="1.0">
<user username="admin" password="admin" roles="admin, admin-gui, manager-gui"/>
</tomcat-users>
7. Migrate the applications
Go to your Tomcat 8 webapps directory:
Copy each war application in the webapps directory from the Tomcat 8 to the Tomcat 9 webapps folder. When you drop a war application into the webapps folder, Tomcats automatically uncompress the application and deploys it.
8. Start Tomcat 9
Go to the [Tomcat install folder]/bin
Start tomcat
C:\Java\apache-tomcat-9.0.0.M10\bin>startup.bat
You should get the following output
Start tomcat
Using CATALINA_BASE: "C:\Java\apache-tomcat-9.0.0.M10" Using CATALINA_HOME: "C:\Java\apache-tomcat-9.0.0.M10" Using CATALINA_TMPDIR: "C:\Java\apache-tomcat-9.0.0.M10\temp" Using JRE_HOME: "C:\Java\jdk1.8.0_40" Using CLASSPATH: "C:\Java\apache-tomcat-9.0.0.M10\bin\bootstrap.jar;C:\Java\apache-tomcat-9.0.0.M10\bin\tomcat-juli.jar"
And a new windows open with the following output.
Tomcat startup output
28-Sep-2016 11:54:28.358 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive C:\Java\apache-tomcat-9.0.0.M10\webapps\TomcatManagerTutorial.war 28-Sep-2016 11:54:28.814 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive C:\Java\apache-tomcat-9.0.0.M10\webapps\TomcatManagerTutorial.war has finished in 456 ms 28-Sep-2016 11:54:28.818 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\docs 28-Sep-2016 11:54:28.846 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\docs has finished in 28 ms 28-Sep-2016 11:54:28.848 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\examples 28-Sep-2016 11:54:29.238 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\examples has finished in 391 ms 28-Sep-2016 11:54:29.240 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\host-manager 28-Sep-2016 11:54:29.275 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\host-manager has finished in 35 ms 28-Sep-2016 11:54:29.276 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\manager 28-Sep-2016 11:54:29.339 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\manager has finished in 63 ms 28-Sep-2016 11:54:29.341 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\ROOT 28-Sep-2016 11:54:29.364 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory C:\Java\apache-tomcat-9.0.0.M10\webapps\ROOT has finished in 23 ms 28-Sep-2016 11:54:29.370 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler [http-nio-8080] 28-Sep-2016 11:54:29.381 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler [ajp-nio-8009] 28-Sep-2016 11:54:29.391 INFO [main] org.apache.catalina.startup.Catalina.startServer startup in 1109 ms
As we can see in this output the war file copied from the Tomcat 8 server was deployed.
console
28-Sep-2016 11:54:28.358 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive C:\Java\apache-tomcat-9.0.0.M10\webapps\TomcatManagerTutorial.war 28-Sep-2016 11:54:28.814 INFO [localhost-startStop-1] org.apache.catalina.startup.HostConfig.deployWAR Deployment of web application archive C:\Java\apache-tomcat-9.0.0.M10\webapps\TomcatManagerTutorial.war has finished in 456 ms
Each time you need to deploy an application in the Tomcat server you can use the Tomcat Manager or you can drop your war files in the webapps folder and Tomcat deploy the web applications automatically.
9. Test the applications
You need to test all applications from the previous installation of tomcat to ensure they work properly.
Open the URL:
Open the manager application.
Write down the credentials imported from the Tomcat 8 installation and you should see the following screen:
As you can see our application is listed here, deployed and running. You also need to check that all your applications works properly.
In this particular case we have only one application migrated from the Tomcat 8 server.
Open the application to ensure it is running.
This application was created for an older Tutorial using Tomcat 8 and successfully migrated to Tomcat 9.
10. Conclusion
Migrate from a new version of Tomcat sometimes is easy but before you start to migrate the application you need to check if your applications run in the new server instance. In this case you can’t run comet applications on Tomcat 9 and you need to re-factor your applications to make compatible with the new installation.
Make a check list of everything you need before migrate a production environment. Create a test environment to check everything works before touching the live environment. Comment all your changes in the Tomcat configuration files.
Write a log of all your changer. If you follow these simple steps you will find it easy to perform a migration of a Tomcat Server.
