Windows 2008r2 - IIS 7.5 - Tomcat 7

15 Apr 2013. How to install Tomcat 7 on a Windows server 2008r2 with IIS 7.5. While I assume you already have a windows server 2008r2 with IIS 7.5 up and running, this document is a step-by-step tutorial installing Tomcat.

• What Tomcat is

1. Install Tomcat
2. Install Tomcat as a Windows Service
3. Use IIS as webserver frontend for Tomcat

• Bonus : Hello World examples (JSP, JavaBean, Servlet, SqlServer)
• Appendix : Acronyms & Concepts
• Appendix : Common Errors & Solutions
• Comments

What Tomcat is

In short Tomcat is a server that executes Java Servlets and JSP web pages.

Tomcat consist of 3 main components :

• Catalina : module that executes Java code servlets.
• Jasper : module that parses JSP files and compile them into Java code servlets, thereby making it possible for Catalina to execute them.
• Coyote : module that listens for http traffic default on port 8080, forwards requests to Tomcat for processing and sends back the result to the requesting client.
• In addition several connectors for integration with other webservers (as alternatives to Coyote) have been created. Specifically in this tutorial we will use the IIS connector to use IIS as a web frontend for Tomcat instead of using Coyote.

Install Tomcat

1. Install Java Development Kit (JDK) :
   While Tomcat is used to execute Java Servlets and JSP web pages, Tomcat is itself build as a Servlet and therefore needs to run on top of the Java Runtime Environment. However here we install the full Java Development Kit (which also contains the Java Runtime Environment).
   1. Download Java SE (JDK comes in different grades, eg. ME, SE & EE, read more here)
   2. Double click on the installer and go through the installation process (select all options).
2. Download Tomcat 7 : choose binary distributions > Core > 64-bit Windows zip (direct link)
3. Extract directly to C:\ drive. Your Tomcat root folder should now be C:\apache-tomcat-7.0.39 (or a newer version) - this is called CATALINA_HOME.
4. Rename C:\apache-tomcat-7.0.39 to C:\tomcat (a more convenient folder for CATALINA_HOME).
5. Setup 2 environment variables :
   1. Open environment variables
   2. Add a system variable called CATALINA_HOME:
      • Name = CATALINA_HOME
      • Value = c:\tomcat
   3. Add a system variable called JRE_HOME
      • Name = JRE_HOME
      • Value = c:\Program Files\Java\jre7
   4. Save and close.
   5. Restart the operating system to be sure the new system variables are fully propagated.
   6. Check the new environment variables are correct :
      1. Open a command prompt.
      2. shell> echo %CATALINA_HOME% : you should get the value c:\tomcat.
      3. shell> echo %JRE_HOME% : you should get the value c:\Program Files\Java\jre7.
6. Open a command prompt.
7. shell> cd %CATALINA_HOME%\bin : Navigate to c:\tomcat\bin.
8. shell> startup : execute the startup.bat file - a new command window is opening starting up the Tomcat server, do not close that command window.
9. Open a browser and navigate to http://localhost:8080 - you should now see the Tomcat homepage.
10. Connect to the Tomcat manager :
    1. Open a browser and navigate to http://localhost:8080/manager/html - the page is password protected.
    2. Open c:\tomcat\conf\tomcat-users.xml in an editor and add the following lines at the end of the <tomcat-users> element :
       • <role rolename="manager-gui"/>
       • <role rolename="manager-script"/>
       • <role rolename="manager-jmx"/>
       • <role rolename="manager-status"/>
       • <user username="tomcat" password="tomcat" roles="manager-gui,manager-script,manager-jmx,manager-status"/>
    3. Save the tomcat-users.xml file and close the editor.
    4. Open a command prompt on c:\tomcat\bin (or return to your command prompt if already open)
    5. shell> shutdown : shutdown the Tomcat server if it was running.
    6. shell> startup : startup the Tomcat server - your changes to tomcat-users.xml should now have been applied.
    7. Open a browser and navigate to http://localhost:8080/manager/html and login :
       • Username : tomcat
       • Password : tomcat
    8. You should now see the Tomcat manager page.

Install Tomcat as a windows service

In a production environment, you don't want to manually startup Tomcat and also would like to avoid having the Tomcat command window hanging. These 2 things can be handled by installing Tomcat as a windows service :

1. Open a command prompt
2. shell> cd c:\tomcat\bin : change directory to the Tomcat bin folder.
3. shell> shutdown : be sure the Tomcat server is shutdown (if Tomcat is already shutdown you will get an error, just ignore the error).
4. shell> service install : install Tomcat as a service.
5. Press windows+r to start windows run box.
6. Write services.msc and hit enter to startup windows services manager.
7. Note that Tomcat 7 is installed as a service but not started.
8. Right click on the Tomcat 7 entry and select Properties from the shortcut menu.
9. In the Apache Tomcat 7 Properties dialog box change "Startup type" from "Manual" to "Automatic" and second press the "Start" button. Then finish starting up click the Ok button.
10. The Tomcat 7 service is started.
11. Open a browser and navigate to http://localhost:8080 - you should now see the Tomcat homepage again.

Note that in the c:\tomcat\bin folder apart from service.bat, 2 other files are involved :

• tomcat7.exe : this is used to startup the Tomcat service (so on OS boot, this file will be called to start the Tomcat process).
• tomcat7w.exe : this is the tomcat executable that runs as a process then the Tomcat service is started by tomcat7.exe.

Use IIS as webserver frontend for Tomcat

Default Tomcat is using the Coyote connector to enable web service so that an http request (typically send by an http browser) can initiate Tomcat to execute a JSP web page and so that the Tomcat execution result can be send back to the initiating http client (typically a browser).

However, here is a step by step guide how to use IIS 7.5 (instead of Coyote) as a frontend for Tomcat 7.

Then IIS is receiving a request for a JSP page or a Servlet, IIS cannot handle such a request on its own, instead we need to configure IIS to forward the request to Tomcat - we will use the JK ISAPI redirector.

1. Change IIS default website to listen to port 82 :
   1. Open IIS manager and right click on the "Default Web Site" and select "Edit Bindings" from the shortcut menu.
   2. From the "Site Bindings" dialog select the row of type http and click the "Edit" button.
   3. From the "Edit Site binding" dialog change the port to 82 and click the Ok button and also close the "Site Bindings" dialog.
2. Create a new website listening on port 80 pointing to c:\tomcat\webapps :
   1. Right click on the IIS "Sites" node and select "Add Web Site..." from the shortcut menu..
   2. In the "Add Web Site" dialog :
      • Name the new website Tomcat.
      • Accept the default to create a new pool called Tomcat.
      • Set "Physical path" to c:\tomcat\webapps.
      • Accept the other defaults, especially notice the port is 80.
      Click the Ok button.
3. Open a browser and navigate to http://localhost/examples/jsp/index.html - you IIS is delivering the static html page.
4. Navigate your browser to http://localhost/examples/jsp/jsp2/el/basic-arithmetic.jsp by clicking on the example link "execute" for the first example "Basic Arithmetic" - you will get an error since we have not setup IIS to be able to handle .jsp requests.
5. Install Tomcat IIS connector :
   1. Download Tomcat IIS connector (select the windows-86_64-iis.zip - direct link).
   2. Extract the file and copy the isapi_redirect.dll to %CATALINA_HOME\bin.
   3. We need to create 3 configuration files :
      • Create a text file called isapi_redirect.properties in %CATALINA_HOME\bin with the following content :
        • extension_uri=/jakarta/isapi_redirect.dll
        • log_file=C:\tomcat\logs\isapi_redirect.log
        • log_level=info
        • worker_file=C:\tomcat\conf\workers.properties
        • worker_mount_file=C:\tomcat\conf\uriworkermap.properties
      • Create a text file called workers.properties in %CATALINA_HOME\conf with the following content :
        • workers.tomcat_home=C:\tomcat\ : your %CATALINA_HOME%.
        • workers.java_home=C:\Program Files\Java\jre7\ : be sure this path is correct.
        • ps=\
        • worker.list=webmodelling : here I list 1 worker and call it webmodelling, you may call it whatever you want.
        • worker.webmodelling.port=8009 : 8009 is the default port for ajp13.
        • worker.webmodelling.host=localhost : Tomcat can be placed on another server on another IP address.
        • worker.webmodelling.type=ajp13 : ajp13 is the protocol to use.
      • Create a text file called uriworkermap.properties in %CATALINA_HOME\conf with the following content :
        • /examples/*=webmodelling : all requests for the examples path should use the webmodelling worker.
   4. Install isapi_redirect as an IIS ISAPI filter :
      1. Open IIS management console.
      2. Select the Tomcat website and double click on the "ISAPI Filters" icon.
      3. In the "ISAPI Filters" screen click on the "Add..." link.
      4. In the "Add ISAPI Filters" dialog give your new filter a name, eg. Tomcat and choose the Tomcat IIS connector, isapi_redirect, as the filter Executable and then click the Ok button.
      5. Back in the "ISAPI Filters" screen, you should now see your new filter, here called Tomcat.
   5. Add the jakarta virtual directory : (matching the extension_uri set in the isapi_redirect.properties file)
      1. In IIS manager right click the Tomcat website node and select "Add Virtual Directory..." from the shortcut menu.
      2. In the "Add Virtual Directory" dialog set :
         • Alias = jakarta
         • Physical path = c:\tomcat\bin
         Click the Ok button to save.
      3. You now have the jakarta virtual directory.
   6. Add the IIS *.jsp handler mapping : (we want IIS to forward .jsp requests to the installed Tomcat ISAPI filter)
      1. In IIS manager select the Tomcat website node and then double click on the "Handler Mappings" icon.
      2. In the "Handler Mappings" screen click on the "Add Script Map..." link.
      3. In the "Add Script Map" dialog set :
         • Request path = *.jsp
         • Executable = c:\tomcat\bin\isapi_redirect
         • Name = JSP : the name is only descriptive, so you can choose anything of you liking.
         Click the Ok button to save - you will be prompted for confirmation that this ISAPI extension is allowed.
      4. In the "Add Script Map" confirmation prompt click the Yes button to allow IIS to forward requests to this ISAPI extension.
      5. You should now see the JSP handler mapping in the "Handler Mappings" screen.
      6. Right click on the JSP handler mapping and select "Edit Feature Permissions..." from the shortcut menu.
      7. Be sure you give the JSP handler mapping execute permission and click the Ok button.
   7. Open a browser and navigate it to http://localhost/examples/jsp/jsp2/el/basic-arithmetic.jsp - Congratulations !

Bonus : Hello World examples

First things first : we need to setup the hello world environment : (you need this environment setup anyway)

1. Create the folder structure :
   1. Create a new folder : c:\tomcat\webapps\myapp\ - this is root folder of the Java hello world examples.
   2. Create a new folder C:\tomcat\webapps\myapp\src\. - to keep our java source files.
   3. Create a new folder C:\tomcat\webapps\myapp\WEB-INF\ - to keep the website descriptor file, web.xml, in which to register the servlet hello world.
   4. Create a new folder C:\tomcat\webapps\myapp\WEB-INF\classes\ - to keep our compiled java classes.
   5. Create a new folder C:\tomcat\webapps\myapp\WEB-INF\classes\MyBeans\ - to keep our javabean compiled class.
2. Specify the worker to use for myapp :
   1. Open c:\tomcat\conf\uriworkermap.properties and add the following line :
      • /myapp/*=webmodelling : here webmodelling is the name of a worker defined in your workers.properties file.
      Save the uriworkermap.properties file.
   2. Restart the Tomcat service.
   3. Restart IIS.
3. Setup the classpath as a system environment variable :
   1. Open environment variables
   2. Add a system variable called CLASSPATH :
      • Name = CLASSPATH
      • Value = .;c:\tomcat\lib\* : the first dot represents current directory, so we instruct JRE to search for user classes in current directory and all jar files in c:\tomcat\lib\.
   3. Restart the operating system to be sure the new system variable is fully propagated.
   4. Check the new system variable is correct :
      1. Open a command prompt.
      2. shell> echo %CLASSPATH% : you should get the value .;c:\tomcat\lib\*.

Ok, we should be ready to go :

• JSP Hello World
• JavaBean Hello World
• Servlet Hello World
• SqlServer Hello World

JSP Hello World

To get a simple .jsp file to execute is the basis of all JSP programming - it is VERY simple (then the JSP environment is correct setup)

1. Create a new text file, helloworld.jsp :

   <html>
   <head></head>
   <body>
   	<% out.println("JSP Hello World"); %>
   </body>
   </html>
   

2. Save helloworld.jsp to c:\tomcat\webapps\myapp\.
3. Open a browser and navigate to http://localhost/myapp/helloworld.jsp.