Skip to main content

Installing Hudson as a Windows Service

Posted by johnsmart on March 17, 2009 at 4:21 AM PDT

I don't usually recommend using Windows for your build server, but sometimes you may not have a choice. You may be running Microsoft tools as an integral part of your build lifecycle, for example, or be constrained to use the local company standards.

Hudson has a very convenient feature designed to make it easy to install Hudson as a Windows servers. There is currently no graphical installer that does this for you, but you get the next best thing - a web-based graphical installer.

First, you need to start the Hudson server on your target machine. The simplest approach is to run Hudson using Java Web Start (see http://wiki.hudson-ci.org/display/HUDSON/Meet+Hudson#MeetHudson-TestDrive). Alternatively, you can do this by downloading Hudson and running it from the command line, as you would normally do:


$ java -jar hudson.war

This second option is useful if the default Hudson port (8080) is already being used by another application. It doesn't actually matter too much which port you use - you can change this later. Next, connect to this server and go to the Manage Hudson screen. Here you will find an "Install as Windows Service" button. This will create a Hudson service on the server that will automatically start and stop Hudson in an orderly manner.

Hudson will prompt you for an installation directory. This will be the Hudson home directory (HUDSON_HOME). The default value is the default HUDSON_HOME value: a directory called ".hudson" in the current user's home directory. This is often not a good choice for a Windows installation. When running Hudson on Windows, you should avoid installing your Hudson home directory anywhere near your "C:\Documents And Settings" directory - not only is it a ridiculously long name, the spaces can wreak havoc with your Ant and Maven builds and any tests using classpath-based resources. It is much better to use a short and sensible name such as "C:\hudson".

Picture 2.png

A short home directory path is sometimes required for other reasons, too. On many versions of Windows (Windows XP, Windows Server 2003,...), file path lengths are limited to around 260 characters. If you combine a nested Hudson work directory and a deep class path, you can often overrun this, which will result in very obscure build errors. To minimize the risks of over-running the Windows file path limits (and without having to reformat your disk and install Ubuntu in its place, an option unfortunately not available to everyone ;-) ), you need to redefine the HUDSON_HOME environment variable to point to a shorter path in the hudson.xml file, as shown above.

This approach won't always work with Windows Vista. The best solution to this problem is to reformat your hard disk and install a proper operating system. If this is not a feasible option, then open the command line prompt as an administrator (right-click, "Run as administrator") and to execute the hudson.exe with the "install" option:


C:\hudson> hudson.exe install

This basic installation will work fine in a simple context, but you will often need to fine-tune your service. For example, by default, the Hudson service will be running under the local System account. However, if you are using Maven, Hudson will need an .m2 directory and a settings.xml file in the home directory. Similarly, if you are using Groovy, you might need a .groovy/lib directory. And so on. To allow this, and to make testing your Hudson install easier, make sure you run this service under a real user account with the correct development environment set up. Alternatively, run the application as the system user, but use the System Information page in Hudson to check the ${user.dir} directory, and place any files that must be placed in the user home directory here.

Picture 4.png

You configure the finer details of the Hudson service in a file called hudson.xml, in the same directory as your hudson.war file. Here you can configure (or re-configure) ports, JVM options, an the Hudson work directory. In the following example, we give Hudson a bit more memory and get it to run on port 8081:

[prettify]
<service>
  <id>hudson</id>
  <name>Hudson</name>
  <description>This service runs the Hudson continuous integration system</description>
  <env name="HUDSON_HOME" value="D:\hdn" />
  <executable>java</executable>
  <arguments>-Xrs -Xmx512m -Dhudson.lifecycle=hudson.lifecycle.WindowsServiceLifecycle -jar "%BASE%\hudson.war" --httpPort=8081 --ajp13Port=8010</arguments>
</service>
[/prettify]

Finally, if you need to uninstall the Hudson service, you can do one of two things. The simplest is to run the Hudson executable with the "uninstall" option:
C:/hudson>hudson.exe uninstall
The other option is to use the Windows service tool sc

C:/>sc delete hudson

"Probably the best training course I've been on."..."Not just how to write Java code but the 'business end' - how to build, test, deploy, manage and monitor"..."One of the best and most useful courses I have attended. And they didn't even try to sell me anything!" - Coming soon to London! Get up to scratch with the latest in Java tools and best practices! Sign up on the 2009 season of the Java Power Tools Bootcamps.

Comments

Quote the year! "The best solution to this problem is to reformat your hard disk and install a proper operating system." Well said, friend!