Deploying Clojure/Java based web app (via Jetty) on Windows and IIS. Step by step guide.

Few words to start with…

I got into clojure programming language some time ago. It took me some time to get into lisp, functional programming and repl-based developement as that was completely opposite to what i have been doing with c# over last couple of years. I find time i have spend with clojure to be very rewarding. More on this some other time.

I have recently completed small clojure based app and i needed to host it somewhere. Web is full of tutorials of how to deploy your clojure app into linux based vm. But i needed something different. Why? I already host couple of my hobby projects on aws’ Windows VM (asp.net/iis) and i just didn’t want to get a linux vm (that you have to pay for and maintain).

Fortunatelly, there is quite an easy step to deploy your clojure (or any java based app) on IIS. Important thing to note here is that this process, that i am goind to present, will only work on windows equipped with IIS 8+. That means you need either Windows Server 2012 or Windows 8 at least.

Although guide below was made specifically for hosting Clojure on IIS via Jetty it can be easily amended to any Java based web application running on either Jetty or Tomcat.

We will start by preparing a simple clojure based web application.

1. Prerequisites

You need Windows machine (at least Windows 8 or Windows Server 2012) with IIS and JDK installed on it.

2. Installing Jetty on Windows

This is straightforward. Just grab recent version from Jetty web site and unzip it to your hard drive. No more work is necessary. Alternatively you may install jetty using chocolatey package. Whatever works for you. After installation your jetty folder should look more or less like that:

3. Preparing WAR file of your web app

As we will be going to host our site via Jetty, we need to prepare a so called WAR file of our web application - creating WAR file is outside scope of this blog post but i will just suggest to use lein-ring plugin to achieve that.

Now, you need to copy such a generated WAR file to webapps folder in your jetty installation path. In my case, as i called app ‘iis-loves-clojure’, webapps folder looks like that:

You can think about your jetty/webapps location as your typical inetpub/wwwroot folder for iis - a default place to keep all your web sites.

That’s it in this part. We are almost ready… Now to the key point:

4. Installing HttpPlatformHandler

Key to running Java apps on Windows is HttpPlatformHandler IIS module. This is relatively new thing, released by Microsoft in early 2015. Apparently it is being used by MS to host Java based app on their Azure cloud platform.

First thing you need to do is to install this module. You can do that via a direct link or using Microsoft’s Web Platform installer.

5. Setting up site on IIS

Once module is installed you can create new web site via your IIS Manager, like on the example below:

Now, just a note, ‘physical path’ that you specify doesn’t have to be a part of your jetty or webapps installation. For now, this can be just an empty folder.

6. Adding web configuration file

In the folder (defined by physical path of just created iis web site) create a new file called web.config. It’s content should look like that:

<?xml version="1.0"?>
<configuration>
    <system.webServer>
      <handlers>
        <add name="httpplatformhandler" path="\*" verb="\*" modules ="httpPlatformHandler" resourceType="Unspecified"/>
      </handlers>
      <httpPlatform processPath="C:\\Program Files\\Java\\jdk1.8.0\_25\\bin\\java.exe" 
                    arguments="-Djava.net.preferIPv4Stack=true -Djetty.port=%HTTP\_PLATFORM\_PORT% -Djetty.base=&quot;C:\\tools\\jetty&quot; -jar &quot;C:\\tools\\jetty\\start.jar&quot;" 
                    startupTimeLimit="20" 
                    startupRetryCount="20" 
                    stdoutLogEnabled="true"></httpPlatform>
    </system.webServer>
</configuration>

Now, this requires an explanation. in configuration/system.webServer/handlers section we have added HttpPlatoformHandler module.

It’s configuration contains processPath - a path to your java.exe from jdk location. Arguments should point to your jetty location (and it’s start.jar file).

You can read detailed explanation of other parametes as well as sample configuration for Tomcat server on Microsoft’s website.

7. That’s it! It should work!

Now you can go to your site. In my case that’s it http://localhost:3333/iis-loves-jetty - subfolder ‘iis-loves-jetty’ is due to the name of WAR file. If you rename your WAR file to root.war then your site should be accessble via just ‘http://localhost:3333/.

That’s it!

comments powered by Disqus