Running Tomcat with IIS on Nano Server

  • Introduction
  • Setup
    • Step 1: prepare Nano server with IIS role and httpPlatformHandler
    • Step 2: install Tomcat on Nano Server
  • Configure settings
    • Step 3: configure server.xml of Tomcat
    • Step 4: configure httpPlatformHandler for Tomcat
    • Step 5: configure Default Web Site
  • Run
  • Troubleshoot

 

Introduction

 

This article shows how to set-up Tomcat and httpPlatformHandler with IIS of Nano server.

 

Setup

 

Step 1: prepare Nano server with IIS role and httpPlatformHandler

 

First you need to install IIS on Nano and then install httpPlatformHandler on your Nano server.

Installing IIS on Nano is already covered in the ariticle below, so I’ll skip those steps here for brevity.

Please notice that the article explains both "Installing IIS" and "Installing the ASP.NET Core Module (ANCM)".
You can skip installing the ASP.NET Core Module (ANCM) because ANCM is not required for running Tomcat on Nano server.

Once you installed IIS on your Nano server, now you are ready to install HttpPlatformHandler on your Nano server.

In order to install HttpPlatformHandler on your Nano server, you have to install it on your regular 64 bit(amd64) Windows machine first in order to get two files, one httpPlatoformHandler.dll and the other httpplatform_schema.xml, copy them to Nano server manually and configure required IIS configurations manually as well.

Here is how to do that step by step.

On a regula 64 bit Windows machine, go to this download page which is for HttpPlatformHandler and download X64 version msi file (httpPlatformHandler_amd64.msi) and execute it to install HttpPlatformHandler on the machine. After HttpPlatform is installed, locate the following two files and copy them to your Nano server onto the same directory.

%windir%\System32\inetsrv\HttpPlatformHandler.dll
%windir%\System32\inetsrv\config\schema\httpplatform_schema.xml

FYI, on purpose, I did not mention about %windir%\Syswow64\inetsrv\HttpPlatformHandler.dll because Nano server does not support 32 bit IIS module and we don't need to copy the 32 bit dll file on Syswow64 directory.

FYI, in case you don't know how to copy any file to your Nano server, I'd like to inform that you can use Copy-Item powershell cmdlet with -ToSession paramerter.
NOTE: in order to use Copy-Item cmdlet for that purpose, you need to configure TrustedHosts for powershell remoting as you did for making the remote powershell tab to your Nano server. 

Here is the example powershell script to copy the two files to a remote Nano server. Modify the ip address of Nano Server with the real one which is used by your Nano server and run it and you will be able to copy the two files to the rigth destination. 

$ip = "<IP address of Nano Server>" # For example, $ip = "10.127.67.20"
$user = "$ip\Administrator"  # supposing you know the password of administrator account on Nano server
$s = New-PSSession -ComputerName $ip -Credential $user
Copy-Item -ToSession $s -Path "$env:windir\System32\inetsrv\HttpPlatformHandler.dll" -Destination C:\windows\system32\inetsrv\
Copy-Item -ToSession $s -Path "$env:windir\System32\inetsrv\config\schema\httpplatform_schema.xml" -Destination C:\windows\system32\inetsrv\config\schema\

After copying the two files to your Nano server, open a remote powershell tab to your Nano server and run the following powershell cmdles to complete installing httpPlatformHandler on your Nano server: 

Import-Module IISAdministration 

Reset-IISServerManager -confirm:$false
$sm = Get-IISServerManager
$appHostconfig = $sm.GetApplicationHostConfiguration()
$section = $appHostconfig.GetSection("system.webServer/handlers")
$section.OverrideMode="Allow"
$sm.CommitChanges()

Reset-IISServerManager -confirm:$false
$sm = Get-IISServerManager
$appHostconfig = $sm.GetApplicationHostConfiguration()
$sectionHttpPlatform = $appHostConfig.RootSectionGroup.SectionGroups["system.webServer"].Sections.Add("httpPlatform")
$sectionHttpPlatform.OverrideModeDefault = "Allow"
$sm.CommitChanges()

Reset-IISServerManager -confirm:$false
$globalModules = Get-IISConfigSection "system.webServer/globalModules" | Get-IISConfigCollection
New-IISConfigCollectionElement $globalModules -ConfigAttribute @{"name"="httpPlatformHandler";"image"="%windir%\system32\inetsrv\httpPlatformHandler.dll"}
 
Reset-IISServerManager -confirm:$false
$modules = Get-IISConfigSection "system.webServer/modules" | Get-IISConfigCollection
New-IISConfigCollectionElement $modules -ConfigAttribute @{"name"="httpPlatformHandler"}

FYI, after running the powershell cmdelts, the c:\windows\system32\inetsrv\config\applicationhost.config in your Nano machine will be updated like this.

...

        <section name="httpPlatform" overrideModeDefault="Allow" />

    </sectionGroup>

</configSections>

...


    <add name="httpPlatformHandler" image="%windir%\system32\inetsrv\httpPlatformHandler.dll" />

</globalModules>

...


<add name="httpPlatformHandler" />

</modules>

...

Step 2: install Tomcat on Nano Server

 

In this step you will set-up JDK and Tomcat on your Nano server.

In order to install JDK to your Nano server, you have to install it on your regular Windows machine. You need a 64 bit OS because you will be using a 64bit JDK.

On a regular 64bit Windows machine where you can install JDK, go to this download page of JDK and download it.

 

http://www.oracle.com/technetwork/java/javase/downloads/index.html

 

You should download the latest build of Java SE Development Kit for Windows x64 platform.

The downloaded file name will be like "jdk-8u66-windows-x64.exe" if the latest JDK's version is "8u66".

Then install the JDK on the regular Windows OS machine. After installation is done, you will see the JDK installation directory has been created under "C:\Program Files\Java\jdk1.8.0_66" or a certain place you choose.

 

Now you need to actually install the JDK onto your Nano server machine.

The installation is very simple. You just need to copy the JDK directory from your regular Windows machine to a certain directory such as c:\ of your Nano server machine.

 

If you copied the JDK directory such as "jdk1.8.0_66" onto c:\ directory of Nano server machine, the directory structure should be like this.

 

[nano1]: PS C:\jdk1.8.0_66> dir

    Directory: C:\jdk1.8.0_66


Mode               LastWriteTime         Length Name                                                                                                             

----               -------------         ------ ----                                                                                                            

d-----         12/10/2015   4:52 PM               bin   

d-----         12/10/2015   4:52 PM               db    

d-----         12/10/2015   4:52 PM               include  

d-----         12/10/2015   4:52 PM               jre  

d-----         12/10/2015   4:53 PM               lib  

-a----       11/9/2015 11:09 AM           3244 COPYRIGHT                                                    

-a----         12/10/2015   4:44 PM       5104608 javafx-src.zip 

-a----         12/10/2015   4:44 PM            40 LICENSE  

-a----         12/10/2015   4:44 PM           159 README.html                                 

-a----         12/10/2015   4:44 PM           527 release 

-a----       11/9/2015 11:09 AM       21244088 src.zip                                                                                                       

-a----         12/10/2015   4:44 PM         110114 THIRDPARTYLICENSEREADME-JAVAFX.txt  

-a----         12/10/2015   4:44 PM         177094 THIRDPARTYLICENSEREADME.txt   

                                                                      

Go to this download page of Tomcat.

http://tomcat.apache.org/download-80.cgi (supposing you're going to install Tomcat v8.0).

 

Then download the "64-bit Windows zip" file. The downloaded file name will be like "apache-tomcat-8.0.30-windows-x64.zip".

Unzip the downloaded zip file and copy its content onto c:\ of your Nano server machine.

 

If you copied Tomcat directory such as "apache-tomcat-8.0.30" onto c:\ directory of Nano server machine, the directory structure should be like this.

[nano1]: PS C:\apache-tomcat-8.0.30> dir

    Directory: C:\apache-tomcat-8.0.30

Mode               LastWriteTime         Length Name                                                                                                              

----               -------------         ------ ----                                                                                                            

d-----         12/10/2015   5:22 PM               bin 

d-----         12/11/2015   2:24 PM               conf 

d-----         12/10/2015   5:22 PM               lib  

d-----         12/11/2015   1:58 PM               logs

d-----         12/10/2015   5:22 PM               temp 

d-----         12/11/2015   1:53 PM               webapps  

d-----         12/11/2015   2:24 PM               work 

-a----       12/9/2015   6:39 PM          58068 LICENSE 

-a----       12/9/2015   6:39 PM           1489 NOTICE  

-a----       12/9/2015   6:39 PM           6913 RELEASE-NOTES   

-a----       12/9/2015   6:39 PM         16671 RUNNING.txt    

 

Configure settings

 

Step 3: configure server.xml of Tomcat

 

Now you have to change the configuration file of Tomcat server which is c:\apatche-tomcat-8.0.30\conf\server.xml of your Nano server machine supposing your Tomcat directory is c:\apatche-tomcat-8.0.30.

The server.xml uses hardcoded value such as 8005 for shutdown and 8080 for startup. That should be changed to be the following:

 

FROM:

...

<Server port="8005" shutdown="SHUTDOWN">

...

<Connector port="8080" protocol="HTTP/1.1"

…

 

TO:

...

<Server port="-1" shutdown="SHUTDOWN">

...

<Connector port="${port.http}" protocol="HTTP/1.1"

...

 

As you can see, you need to change 8005 with -1 and 8080 with ${port.http}.

 

The value for ${port.http} will be set by httpFlatformHandler on runtime with an available TCP port number at that time. The value of the shutdown port, -1, is not actually used because the Tomcat server process runs as a child process of the IIS worker process, and it will be shut down automatically when the IIS worker process is shut down.

 

Step 4: configure httpPlatformHandler for Tomcat

 

Create a web.config file after creating a directory such as c:\inetpub\website1 and fill the file with the following content in order to configure httpFlatformHandler for Tomcat.

NOTE: This sample web.config has hardcoded values of C:\apache-tomcat-8.0.30, c:\jdk1.8.0_66 and C:\inetpub\website1. You have to adjust those values to match your Nano server environment. While adjusting values, make sure every value is pointing valid existing directory path. 

<?xml version="1.0" encoding="UTF-8"?>

<configuration>

  <system.webServer>

    <handlers>

       <add name="httpplatformhandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />

    </handlers>

    <httpPlatform processPath="C:\apache-tomcat-8.0.30\bin\startup.bat" arguments="" stdoutLogEnabled="true" stdoutLogFile="\\?C:\inetpub\website1\log.txt">

       <environmentVariables>

         <environmentVariable name="JRE_HOME" value="c:\jdk1.8.0_66" />

         <environmentVariable name="CATALINA_OPTS" value="-Dport.http=%HTTP_PLATFORM_PORT%" />      

         <environmentVariable name="CATALINA_HOME" value="C:\apache-tomcat-8.0.30" />

       </environmentVariables>

    </httpPlatform>

    <directoryBrowse enabled="true" />

  </system.webServer>

</configuration>

 

I'd like to inform that the line enabling directoryBrowse is optional. If you enable it, it will be useful while troubleshooting. For example, you can temporarily remove the config sections of handlers and httpPlatform to check if the website works without httpFlatform.

 

Step 5: configure Default Web Site

 

Open applicationhost.config file which is placed in c:\windows\system32\inersrv\config and edit the physicalPath of Default Web Site with the "c:\inetpub\website1" where you created web.config file.

 

Run

 

Now you are ready to start. In this section you will learn how to verify Tomcat and create a sample web application.

 

Step 6: start http://<ComputerName>

 

Restart IIS services first. You can use the commands "Stop-Service was -Force -Confirm:$false" and "Start-Service w3svc".

Now you are ready start. On any client machine from which you can connect to your Nano server machine, open a web browser such as IE and browse http://<ComputerName> (NOTE: replace <ComputerName> with the computer name of your Nano server) and you will get this result if everything is okay.

Note: the first request will take some time because it takes some time to start Tomcat.

 

Step 7: add sample webapp and run http://<ComputerName>/sample

 

You can download a sample Java web application and install it onto your Tomcat directory.

Download the sample directory from https://tomcat.apache.org/tomcat-6.0-doc/appdev/sample/ and copy onto C:\apache-tomcat-8.0.30\webapps, after which a new directory such as C:\apache-tomcat-8.0.30\webapps\sample will be created.

Now, you are ready to test the sample web application with browsing http://<ComputerName>/sample.

 

Troubleshoot

Here are common mistakes I made which caused up to an error of 500 and how I fixed those issues. Check these thing if you run into similiar issue.

  1. Make sure the httpPlatform configuration section should be added inside the sectionGroup of "system.webServer", not "system.applicationHost"
  2. Make sure overrideModeDefault of the httpPlatform configuration section is set to "Allow"
  3. Make sure that the server.xml for the Tomcat server is configured correctly
  4. Make sure web.config is configured correctly, especially for directory paths
  5. You might need to restart IIS services after making configuration changes in order to apply the change
  6. You might need to restart your web browser with clearing cached result to see the updated result after making configuration changes

You might want to know how to run the Tomcat server on your regular (non-Nano) Windows machines in order to confirm that your downloaded Tomcat server  works well before installing it onto your Nano server machine.

After installing Tomcat server on regular Windows machine, run the following commands to start Tomcatserver on regular Windows machine:

set JRE_HOME=%programfiles%\Java\jdk1.8.0_66

set CATALINA_OPTS=-Dport.http=1234

set CATALINA_HOME=C:\dev\javasites\bin\apache-tomcat-8.0.30

C:\dev\javasites\bin\apache-tomcat-8.0.30\bin\startup.bat

After running this, you will see the Tomcat server running while using TCP port 1234.

Then, browse http://localhost:1234 and verify that you got the right result.

 

No Comments