Hudson CI Server – A quick start guide

Introduction

Continuous Integration is a software development practice where members of a team integrate their work frequently, usually each person integrates at least daily – leading to multiple integrations per day.
- Martin Fowler

Hudson is a popular open-source continuous integration server used by many organizations like Redhat JBoss. Though there are many well known and well established open-source projects like CruiseControl, Continnum and some commercial offerings like Bamboo, what makes Hudson special is it’s powerful yet easy to use web interface, it’s simplicity and it’s extensible architecture with many plugins.

Objective

The objective of this tutorial is to setup, configure and learn to use Hudson by building “Apache Commons IO“, a well known java project.

Requirements

• Hudson
• Subversion (or any other version control system like CVS, Mercurial, Git if you want to build your own project)
  
• (Optional) Tomcat or Glassfish
• Apache Ant (or Maven)
  

Installation and Starting Hudson

Installing Hudson is super easy. Just download the war file, open your terminal/command-prompt and issue the command “java -jar hudson.war”. Now point your browser to http://localhost:8080. That was easy, right?

Hudson has an embedded servlet container called “Winstone” which works much like a standard servlet container like Tomcat by serving your JSP pages and servlets.

If you want Hudson to start on a different port, say 8180, issue the following command,
<code> java -jar hudson.war –httpPort=8180 </code>

Ofcourse you can deploy Hudson to Tomcat, Glassfish or any other supported servlet containers. The following guides can be useful in that case:

• Hudson and Tomcat
• Hudson and Glassfish

More container specific guides can be found from this hudson wiki.

Once you started Hudson or deployed it to a servlet container, this is what you might see in your browser when you start Hudson for the first time.

Hudson Home Directory

All your Hudson jobs/settings are stored in the Hudson home directory. If you did not specify one, Hudson shall assume some defaults like <code> ~/.hudson </code> in Linux or your respective home directory in Windows. It’s ok to go ahead with the defaults while you test drive Hudson but once you are done, I strongly recommend you to define a Hudson home directory of your choice, preferrably on a separate partition or drive. This will ensure that all your Hudson configuration/jobs are intact in case of any system crash.

Say, suppose your home directory is “/hudson” (in Linux), this is how you will define the Hudson home directory,

If you are using the embedded servlet container, start it by specifying the java system property “HUDSON_HOME”,
<code> java -DHUDSON_HOME=/hudson -jar hudson.war </code>

If you are using Tomcat, follow the explanations in this wiki. However, if you run Tomcat as a windows service, you need to do some tweaking to let Tomcat set this property. In that case, you will be better off if you start Tomcat using it’s batch file and set the property right there. (Or if you managed to run Tomcat as a Windows Service and still able to define the Hudson home correctly, why don’t you share your views with us?)

If you are using Glassfish, go to admin console and add the JVM option <code> -DHUDSON_HOME=/hudson</code>. More detailed explanations can be found on this wiki.

Just remember that the idea is to define a system property “HUDSON_HOME” through any of the possible ways.

This is how the Hudson home directory shall look like.

Manage Hudson

Hudson provides an easy to use web interface to manage the configurations needed to administer a continuous integration server. Let us do some basic configurations to get Hudson ready.

Start Hudson and click the “Manage Hudson” link located on the left.

Now click “Configure System”. Hudson will display a page where you can configure things like access control, JDK, Ant, Email Settings etc.

Access Control

We will enable security to secure our Hudson setup. Otherwise anybody can go and meddle with your Hudson jobs. If you don’t want that to happen, check the “Enable Security” checkbox.

Once security is enabled, we need to tell Hudson the type of “Access Control” we want to use. Let us choose the Security Realm as “Hudson’s own user database” and leave the option “Enable users to signup” as checked. (If you do not check the “sign up” option here, Hudson is definitely going to whack you later!. ) Under the “Authorization” section, choose “Matrix-based Security”.

Now add an user called “administrator” and give the necessary privileges. ENSURE THAT YOU GIVE “ADMINISTER” PRIVILEGES TO THIS USER or else, you may not able to access the administrative console once security and access control are enabled. (Again, if you miss it, Hudson is gonna whack you!)

Hudson will display an error symbol near the user we just added. That’s because the user does not exist  in the system. Do not bother, we will create the user a little later. Now go ahead and add users who might be accessing Hudson. Give appropriate access controls to the users and do not give full access to everyone. That will eventually create a system that is difficult to manage.

Configure JDK

Done with security? Now we need to configure the JDK which Hudson shall use to build the jobs. Find out the section “JDK” in the same page. Click the “Add JDK” button and then enter the details of your JDK.

Configure Ant

We need to tell Hudson where Ant is located. Find out the section called “Ant”, click “Add Ant” and enter the respective details.

(Follow the same procedure, if you want to configure Maven.)

That’s it! Hudson is now almost ready for prime time. Feel free to configure the Email Settings as well with the appropriate values. When you are done, press the “Save” button to save all the changes you have made.

Once you press the “Save” button, Hudson will redirect you to a login page.

Manage Users

Click the “Signup” link at the top right corner of Hudson and register a new user called “administrator” (or whatever name you gave in the “Access Control” section).

Hudson will automatically login the user provided the user was already configured in the “Access Control” section. Once a new user (administrator) is registered in the system, Hudson will provide an option called “Manage Users” in the “Manage Hudson” page.

You can now create other users from this page.

You will be using this page to manage all your Hudson users. Looks like we have covered quite a lot of information. It’s time now to create some jobs and see Hudson in action.

Creating Job

That’s the core feature of Hudson. Hudson jobs can fetch the source code from a repository, execute your build scripts, run your tests, prepare javadoc, notify you in case of any failure, archive the build artifacts and much more. That’s where you can really see the power of Hudson. Enough talking, let us explore these Hudson features now by creating a job.

The Hudson job which we are going to create now is going to be very simple and is capable of doing the following:

• Checkout the source code of apache commons-io project using subversion
  
• Run the build script (build.xml in case of Ant, pom.xml for Maven)
• Archive the build output
  

Create a job by clicking the link “New Job” on the left. Give a name for the job, select the option “Build a free-style software project” and then press “OK”.

Configure Job

Hudson will create a new empty job for us which we need to configure.

Let us configure the repository for this job first. Go to the section “Source Code Management”, choose the option “Subversion” and enter the repository url  as “http://svn.apache.org/repos/asf/commons/proper/io/trunk“. Enter the “Local module directory” as  “.”

Look for the section called “Build”. Click the button “Add build step” and select “Invoke Ant”. Leave the rest to default. (Maven users, choose the appropriate action)

Go to the section “Post-build Actions”. Select the checkbox “Archive the artifacts”. The apache commons-io build script shall create the jar in the directory named “target”. So enter the value “target/*.jar” in the text field titled “Files to archive”. Though this is not mandatory to build a job, I recommend you to do this as this will help the users of your continuous integration server to download the build outputs quickly.

NOTE: Since we are building the apache-commons-io project we are entering the value “target/*.jar”. If for example, your build output directory is “dist”, then you should enter here as “dist/*.jar”.

Press the “Save” button at the bottom. Our job is ready and just click link “Build Now” at the left to start building the job.

Once the build is initiated, you can relax and watch the progress in the “Build History”.

If you are restless and want to see exactly what is going on, just click the link (corresponding to the build number) in the “Build History”.

Now click the link “Console Output”.

Hudson will display you the console view where you can do all your research.

Now that the build is successful, you might want to have a look at the jar built by this job. You can find that under “Last Successful Artifacts”.

You can also have a sneak preview about the builds from your Hudson home page.

If in case some of your builds failed, Hudson will report that as well neatly along with displaying the build stability.

That’s it for now. But you can do a lot more like configuring Hudson to build this job every few minutes or just poll the repository once in a while and trigger the build whenever someone commits to the repository. Explore them under the job’s configuration page and enjoy. And did I mention that Hudson has a lot of good plugins already? Maybe I will try to cover those advanced concepts in my next post.

If you are using NetBeans as your IDE, then you have a got a lot of Hudson features integrated right into the NetBeans IDE. Check that out in my post NetBeans 6.7 – A quick glance.

Are you using Hudson? Are you planning to use Hudson? Why not leave a comment below and share your thoughts?

Read also: “NetBeans and Maven – A quick start guide”