Front-ending Apache Tomcat with Apache Web Server or IIS is sometimes thought to improve performance. However, performance of Tomcat standalone has already been known to be very good. So why add IIS or Apache web server in front of it? – the answer is scalability and maintenance. Front-ending Tomcat with such web servers allows you to add more instances in case of increased load and also bring down instances for maintenance/upgrades.
This blog shows you end-to-end, step-by-step detailed instructions on how to setup such an environment. It should take you about an hour to configure this setup for yourself. Follow the instructions slowly and carefully to make sure you do not skip/miss any step. Here is a higher level view of the setup.
Environment: Windows 7 Professional, Tomcat 7, IIS 7.5, Java SE 6 Update 29
You need to perform the following steps:-
- Install Java
- Install IIS
- Install Tomcat
- Configure Tomcat
- Configure IIS
- Create and deploy a web application
You will be installing Java SE 6 Update 29. Download the JDK from http://www.oracle.com/technetwork/java/javase/downloads/index.html. Once downloaded, double-click on the exe file to kick-start the installation. In the installation wizard, accept the defaults and finish the installation.
You now need to set the JAVA_HOME environment variable to point to the JDK installation directory.
- Open Windows Explorer
- Right-click on Computer and select Properties. This opens the System Properties window. Click on the Advanced tab and then click on Environment Variables
- In the section User variables for Administrator, click on the New button. Enter JAVA_HOME for Variable name:. For Variable value, enter the absolute path of the directory where the JDK is installed. For example, on my machine it is installed at C:\Program Files\Java\jdk1.6.0_29
Installing IIS is fairly straightforward. Apart from IIS, you will also install some extra components, which you will see shortly.
- Go to the Control Panel and click on Programs and Features. Click on Turn Windows features on or off.
- In the Windows Features window, check Internet Information Services and Microsoft .NET Framework 3.5.1.
- Expand Internet Information Services and under World Wide Web Services – Application Development Features, check ISAPI Extensions and ISAPI Filters.
- Click OK to finish installation.
Install Tomcat 7
- Download Tomcat 7 from http://tomcat.apache.org/download-70.cgi. Download the 64-bit Windows Zip file.
- Unzip the file to your c:\ drive and a directory named apache-tomcat-7.0.xx will be created, where xx is the minor version number.
- Rename that directory to tomcat.
- This finishes your Tomcat installation.
In order to distribute load across multiple instances of Tomcat, we need to create two more instances of Tomcat.
- Create two directories named tomcat1 and tomcat2, directly under c: drive.
- Within both these directories, create the following sub-directories – bin, conf, logs, webapps, temp, work.
- From c:\tomcat\conf, copy server.xml, web.xml, context.xml and tomcat-users.xml, and paste them into the conf directories of tomcat1 and tomcat2
- Copy startup.bat and shutdown.bat from c:\tomcat\bin and paste them in the bin directories of c:\tomcat1\bin and c:\tomcat2\bin
- Edit startup.bat and shutdown.bat of tomcat1 and at the very top of these files, add the following lines:
Repeat step 5 for tomcat2 with the exception that CATALINA_BASE should be set to c:\tomcat2
Lets go through some concepts/terminology before we begin configuration.
A connector in Tomcat is something which allows a client to connect to Tomcat. Tomcat ships will multiple connectors e.g. HTTP, AJP etc. By default, the HTTP connector is configured to listen on port 8080. In our case, the IIS server will act as a client to Tomcat. IIS web server will communicate with Tomcat using the AJP protocol. We need to ensure that we have the ports for the AJP connector configured. We also want all requests to be routed through IIS and do not want anybody to bypass it, i.e we do not want anybody to access the web application through port 8080 using the HTTP connector. Hence, we will disable (comment) the HTTP connector from our configuration.
A worker is simply an instance of Tomcat to which IIS will dispatch requests. In this case, all three Tomcat instances will be workers. Each worker needs to have a unique id, which will be assigned to it using the jvmRoute attribute of the <Engine> element in server.xml. You will see later how and where this id is used by IIS server. Lets start configuring the Tomcat instances:
- Change Shutdown ports:- All three Tomcat instances will reside on the same machine, hence we need to ensure that ports do not conflict. Shutdown ports are where Tomcat listens for the shutdown command. Open server.xml of each tomcat1, locate the <Server > element start tag and change the port number to 8006. Repeat this step for tomcat2 and change the port number to 8007.
- Change AJP ports :- In server.xml of tomcat1, locate the <Connector> element whose protocol=”AJP/1.3″ and change the port number to 8010. Similarly for tomcat2, change the port number to 8011
- Disable HTTP Connectors:- In the server.xml of each Tomcat instance, locate the <Connector> element shown below and either delete it or comment it out
<Connector port=”8080″ protocol=”HTTP/1.1″ connectionTimeout=”20000″ redirectPort=”8443″ />
- Assign worker ids:- In server.xml of tomcat, locate the <Engine> element and add the following attribute to its start tag jvmRoute=”worker0″ (the value of the attribute is workerZERO and not workerOH). Repeat this step for tomcat1 and assign the value of worker1. Similarly repeat for tomcat2 and assign the value of worker2.
You will now configure ISAPI redirector plug-in provided by Tomcat. The redirector requires 4 entities:-
- isapi_redirect.dll : This is the IIS plugin which you will download later
- worker.properties: A file that describes the hosts and ports of workers (Tomcat instances/processes)
- uriworkermap.properties: A file that maps URL patterns to workers. Allows you to specify as to which worker will handle the matching URL path request
- isapi_redirect.properties: A file which tells IIS the location of all of the above files.
Lets start the configuration. After you installed IIS, it would have created a directory named c:\inetpub. All configuration will be done in the c:\inetpub directory.
- Under c:\inetpub, create a subdirectory called isapi. Under c:\inetpub\isapi, create three subdirectories – bin, logs, conf.
- To download the isapi_redirect.dll, go to http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/windows/ and download the zip appropriate for your system i.e. 32-bit or 64-bit.
- Unzip the downloaded file and copy isapi_redirect.dll and paste it under c:\inetpub\isapi\bin
- Inside c:\inetpub\isapi\conf, create a file named worker.properties. In this file you will create workers, their host and the port on which they will communicate with IIS. Workers are of different types e.g. ajp13 is a worker which communicates with web server i.e. tomcat instances , lb is the worker which will act as the load balancer, stats worker type will give you load balancing statistics and status information. You will be adding key-value pairs, each key must begin with the word worker. The complete worker.properties file is shown below. Copy/paste the below to your worker.properties file and save it. Explanation of each line is given above the line in a commentCould not embed GitHub Gist 1440048: Bad credentials. The API can't be accessed using username/password authentication. Please create a personal access token to access this endpoint: http://github.com/settings/tokens
- Inside c:\inetpub\isapi\conf, create a file named uriworkermap.properties. In this file you will map the workers to the URL path patterns. This will tell IIS, which worker will handle a request for a given URL path. As you can see below, the /foo web application is mapped to the load balancer worker, which the /jkstatus path is mapped to the stats worker.Could not embed GitHub Gist 1440060: Bad credentials. The API can't be accessed using username/password authentication. Please create a personal access token to access this endpoint: http://github.com/settings/tokens
- Inside c:\inetpub\isapi\bin, create a file named isapi_redirect.properties. This file will tell IIS, the location of isapi_redirect.dll, worker.properties, uriworkermap.properties and the location of the log file for the redirector plugin. You can copy/paste contents from the file as shown below.Could not embed GitHub Gist 1440072: Bad credentials. The API can't be accessed using username/password authentication. Please create a personal access token to access this endpoint: http://github.com/settings/tokens
The remainder of the configuration is through the IIS Manager:
- To open the IIS Manager, open Administrative Tools from the Control Panel and then click on Internet Information Services (IIS) Manager
- You will now create a Virtual Directory named tomcat. Under Connections, navigate to [[Root Node]] > Sites > Default Web Site. Right-click on Default Web Site and select Add Virtual Directory. For Alias enter tomcat, and for Physical Path, enter C:\inetpub\isapi\bin. Click OK to close the Edit Virtual Directory window.
- To configure Handler Mappings, under Default Web Site, select tomcat. In the Features View pane, double-click on Handler Mappings and then select ISAPI-dll, which should be disabled at the moment. Now in the Actions pane, select Edit feature permissions. In the Edit Feature Permissions window, check the Execute option and click OK to close the window. ISAPI-dll should now be enabled.
- You now need to configure the ISAPI Filter and specify the location of the dll. Select Default Web Site . In the Features View pane, double-click on ISAPI Filters. From the Actions pane, click on Add. For Filter Name, enter isapi_redirect. For Executable, enter the absolute path of the location of the isapi_redirect.dll — C:\inetpub\isapi\bin\isapi_redirect.dll.
- Finally, you have to now enable the ISAPI extension which you have configured above. In the Connections pane, click on the root node. In the Features View pane, double-click on ISAPI and CGI Restrictions. In the Actions pane, click on Add. This will open the Edit ISAPI or CGI Restrictions window. For the ISAPI or CGI Path field, enter the absolute path of isapi_redirect.dll — C:\inetpub\isapi\bin\isapi_redirect.dll. In the Description field, enter isapi_redirect. Also make sure to check the option Allow extension path to execute. Click OK to close this window.
- This step is only for those who have downloaded a 32 bit version of isapi_redirect.dll, but have a 64 bit operating system. If you already downloaded the 64 bit version, then please ignore this step. Click on [[Root Node]] > Application Pools. In the Features View pane, select DefaultAppPool and then click on Advanced Settings… in the Actions pane. In the Advanced Settings window, under the (General) section, set Enable 32-Bit Applications to true. Click OK to close the Advanced Settings window.
Create and deploy a web application
You will now create a web application named foo and deploy it to all the Tomcat instances. You can perform the following steps with Notepad, no need to fire up an IDE. You will be able to copy/paste most of the stuff.
- In c:\tomcat\webapps, create a directory named foo. Within this directory, create a subdirectory named WEB-INF. Within WEB-INF, create two sub-directories named classes and lib.
- Within the foo directory, create a file named index.jsp. This JSP will simply display the Session ID and Session Creation Time . You can copy the code snippet (below) into the JSP.Could not embed GitHub Gist 1440233: Bad credentials. The API can't be accessed using username/password authentication. Please create a personal access token to access this endpoint: http://github.com/settings/tokens
- Copy the foo directory (and all of its contents) into c:\tomcat1\webapps and c:\tomcat2\webapps
Its now time to test your setup.
- Start each tomcat instance, but double-clicking on startup.bat in the bin directories of each tomcat.
- To start IIS, go to IIS Manager and Start or Restart (whichever is applicable) IIS from the Actions pane.
- Open a browser and navigate to http://localhost/foo. You should see the output from index.jsp. Notice how the value of jvmRoute attribute has been suffixed to the session id. This tells you the tomcat instance serving this request
- Open another browser and navigate to http://localhost/foo, you should now see a different tomcat instance servicing the request. Try it with a third browser and you should see the response from the third instance.
Congratulations, you have configured load balancing using Tomcat 7 and IIS 7.5 !
You’ve had to edit configuration files for different Tomcat instances. This requires you to switch between those instances frequently. MuleSoft Tcat – Enterprise Tomcat , has the capability to provide you with a unified front-end for all your Tomcat instances. You would have been able to perform operations (startup and shutdown) and edit configurations of multiple Tomcat instances, all from the Administration Console.