Deploying Jenkins to a Subdirectory using IIS on Windows Server 2016

If you’re here, I’m going to assume you know what Jenkins is, why you might want to use it, and why you would want a reverse proxy in front of it (*cough* HTTPS, *cough* hacking your CI server lets people run whatever commands they want on your machine). I’m not here to tell you what you already know or how to configure Jenkins for your project.

I’m here to, hopefully, help someone out who is in similar shoes to those I was in, struggling to get IIS and Jenkins to play nicely together, because it needn’t be difficult.

Installing Jenkins

Whenever possible, I use Chocolatey (think apt-get for Windows) to install software, and I highly recommend it; downloading .exes is so 2010.

To install Jenkins, it’s about as simple as it gets…

cinst -Y jenkins

If all went well, Jenkins should be started after installation completes. One of the advantages of installing via Chocolatey are that it automatically sets up a Windows service and enables it so that Jenkins will be started at boot.

Before turning our attention to IIS though, we need to tell Jenkins about our prefix (subdirectory). To do this, open C:\Program Files (x86)\Jenkins\jenkins.xml and add --prefix=/jenkins to the <arguments> entry.

Restart the service with Restart-Service jenkins and confirm everything is working by visiting http://localhost:8080/jenkins in your browser; you should see the initial setup page.

Configuring IIS as Reverse Proxy

You will need the URL Rewrite and Application Request Routing modules installed. I’d love to give you a nice little one liner, but alas, Windows is not Linux. Download the .exes and do the drill.

Once those have been installed, open IIS Manager and navigate to the URL Rewrite settings for the website which Jenkins should live under (9/10 times, this is “Default Web Site”).

First, we need to add a rule for IIS to forward all requests to /jenkins/* to the Jenkins servlet. Click “Add Rule(s)” from the menu on the right, select “Reverse Proxy,” and in the window that pops up, enter localhost:8080 as the forwarding address, and click OK.

We aren’t done with this rule however; as it stands it will send every request to Jenkins. To restrict proxying to our /jenkins subdirectory, double click on the newly created rule and add your prefix to the pattern inside the matching group; you want to ensure that the prefix is included in the URL proxied to Jenkins. Your final inbound rule should look something like this:

At this point you should be able to access Jenkins via IIS. Visit mycooldomain.com/jenkins to complete setup and configure your Jenkins instance. Note, you’ll want to set the “Jenkins URL” to your FQDN under Manage > Configure System.

And that’s it!