Copyright © 2011 Oracle, Inc.. All rights reserved.

Online version published by Oracle, Inc., 500 Oracle Parkway, Redwood Shores, CA 94065.

Hudson is a registered trademark of Oracle, Inc., in the United States and other countries.

Nexus™, Nexus Professional™, and all Nexus-related logos are trademarks or registered trademarks of Sonatype, Inc., in the United States and other countries.

Java™ and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle, Inc., in the United States and other countries.

IBM® and WebSphere® are trademarks or registered trademarks of International Business Machines, Inc., in the United States and other countries.

Eclipse™ is a trademark of the Eclipse Foundation, Inc., in the United States and other countries.

Apache and the Apache feather logo are trademarks of The Apache Software Foundation.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and Oracle, Inc. was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

Foreword: 1.0

This book covers Hudson, the most widely used open source Continuous Integration Server. Oracle is excited to support the continued development of Hudson as the Hudson community completes its transition to the Eclipse Foundation. An important part of making sure that Hudson offers a supportable, world-class experience to end users is quality documentation.

If you have any feedback or questions, you are encouraged to post on the Hudson project mailing lists, or to contact the authors directly via the Hudson project. We’re here to help, and we look forward to your feedback.

Manfred Moser, Tim O’Brien

August, 2011

Edition: 1.0

Introducing Hudson

What is Hudson?

Hudson is a powerful and widely used open source continuous integration server providing development teams with a reliable way to monitor changes in source control and trigger a variety of builds. Hudson excels at integrating with almost every tool you can think of. Use Apache Maven, Apache Ant or Gradle or anything you can start with a command line script for builds and send messages via email, SMS, IRC and Skype for notifications.

In addition to providing a platform for continuous integration builds, Hudson can also be extended to support software releases, documentation, monitoring, and a number of use cases secondary to continuous integration. In short, if you can think it, Hudson can do it. From automating system administration tasks with Puppet and verifying infrastructure setup with Cucumber, to building and testing PHP code, to simply building Enterprise Java applications - Hudson stands ready to help.

Continuous Integration

Martin Fowler and Kent Beck are largely credited with the first use of the term "Continuous Integration" as applied to software development with Beck’s seminal 1999 book Extreme Programming Explained being the first published work touching upon the idea of creating systems to continuously build and test systems in response to changes in source control. In the decade since this concept was introduced, continuous integration is now an established, standard practice used across an entire industry.

Note Beck, Kent (1999). Extreme Programming Explained. ISBN 0-201-61641-6.

The idea, put simply, is that software development efforts are much easier to manage when test failures and other bugs can be identified closer to the time they were introduced into a complex system. Let’s examine the differences between a development effort using a Continuous Integration server, and a development effort not using Continuous Integration.

A Hypothetical Development Team

Consider a hypothetical group of 20-30 developers working on a large enterprise application.

This development team consists of 20-30 developers divided into groups of 5-12 developers working on focused features and components in a larger system. One group focuses on the database and a collection of APIs shared by all other groups, one group focuses on a complex front-end web application, and another group focuses on back-end systems such as billing and inventory which interface with a large Enterprise Service Bus (ESB).

In this environment the business drives a number of overlapping development schedules. The web application team tends to work on two week development schedules, and the back-end group performs releases in response to changes in the ESB. Any given month resemble a highly choreographed sequence of code freezes, development sprints, and products releases with little room for error and inefficiency.

In summary, these 20-30 developers are under constant pressure to deliver, and the technical managers are tasked with orchestrating the efforts of these various teams to deploy code to production on a regular schedule. This is what the enterprise feels like in 2011: it’s very busy, and if you happen to find a bit of free time there is always someone who can create a new requirement.

Without Continuous Integration

Without Continuous Integration the various teams have to factor in "integration time" into the schedule. Unit tests might be run by individual developers, but integration tests are only executed when the system is ready to be deployed. There’s nothing automatic about the process, and, very often only a handful of developers have the appropriate environment to build and deploy to production.

Each team, each group is responsible for testing the larger system and making sure that their changes don’t interfere with another group’s changes. One week before a release, everything stops so that a single "release manager" can build a canonical build on a single build machine and deploy this build to a testing environment.

Each time one group needs to deploy a specific part of the system, every group needs to stop, synchronize, and test. If the web application group needs to deploy to production, all of the other groups need to synchronize with that group and make sure that all of the tests pass during a build.

This constant need to stop, integrate, and verify introduces a synthetic limit to the scale of development. As development teams scale and grow larger, and as systems become increasingly complex and intertwined your team spends more time on integration and testing.

Without continuous integration, developing modern applications is practically impossible without dramatic inefficiency. There is too much unproductive down-time, and far too much waste. The development group described above would be hard pressed to release anything more than a global update once a month.

With Continuous Integration

With Continuous Integration, the system completes a build, test, deploy, and integration in response to every single commit. If a developer in the web application group checks in code at 2 AM, Hudson kicks off a build, runs unit tests, deploys the code to a new server, and performs a set of integration tests. If this build fails or the tests encounter an unexpected condition, everyone is notified of this failure.

With continuous integration, no one needs to drop everything and run a release build, these builds are generated every single day, and in the most mature environments, a fully tested and verified system can be deployed to production at any time. In other words, when you automate build, test, and verify using a tool like Hudson you can continue developing your applications without having to wait (or synchronize) on some manual build, test, verify process.

Making these processes automatic has another important side-effect, it makes the development process more scale-able. When your teams don’t have to stop to actively test and collaborate with one another, it is much easier to add additional developers to a project. Without continuous integration you have to stop and synchronize release schedules. With continuous integration you reduce the risk associated with a particular software development cycle.

Minimizing Technical Debt

Another way to think about Hudson is in terms of technical debt.

When you amass "technical debt" you are making a decision that yields a short-term benefit while creating a problem to be solved in the future. If you’ve developed code under strict time lines, technical debt is nothing new to you. Every system has some form of technical debt. If you’ve ever sacrificed quality for the expedient solution, you’ve experienced technical debt: "the code had to be deployed tomorrow and the deadline was fast approaching".

From the perspective of builds and tests, it is much easier to develop a system without having to worry about unit tests and integration tests. You could speed up implementation time for a feature by just skipping the tests, but you’ll eventually pay for this approach ten-fold in the form of bug fixes.

Continuous integration along with a commitment to test-driven development helps minimize your exposure to risky technical debt. Because you are running the unit and integration tests every few minutes, you don’t have the opportunity to let problems sit and fester unaddressed. When you develop without continuous integration, you are amassing the potential for technical debt. You can choose to fix bugs as they are introduced, minimizing both the scope and severity of defects by catching them early, or you can develop for weeks and run tests only at the end of the development cycle.

While you might only deploy to production once a month, your Hudson installation deploys once a commit, and when you are dealing with increasingly complex systems this granularity makes sure that any glaring quality detours are confined to a single commit.

Push it to Production with Hudson

The infrastructure that powers applications has grown more and more complex over time. The web application that ran on a production network of 10 hefty Unix machines in 1999 has evolved into an architecture that can potentially span hundreds (or thousands) of nodes on a computing grid. Companies like Apple and Oracle are deploying infrastructure on a massive scale compared to where the industry was operating just a few years ago. This movement toward Cloud-based deployments and Platform-as-a-Service (PaaS) has meant that infrastructure is now more likely to be compiled and deployed on an as-needed basis.

Organizations are using tools like Hudson to setup production deployments and automate the management of cloud-based infrastructure. This carries the idea of Continuous Integration forward into the realm of Continuous Deployment. While the idea may sound risky if you work in a relatively slow-moving industry, social networks like Facebook and social media services such as Flickr have been building complex developer/operations (devops) systems that allow them to deploy code to production multiple times a day.

While this emerging trend is still confined to the largest deployments, the idea of connecting your Continuous Integration server directly to your production systems is gaining support. Hudson can be a critical part of automating these approaches to continuous deployment. Proven integration with tools like Puppet and Cucumber allow innovative devops staff to take continuous integration in some surprising directions.

General Purpose Scheduler

Hudson can also be viewed as a general purpose scheduler, a replacement for cron or Quartz in your production network. While Hudson is generally viewed as development infrastructure, a class of infrastructure usually considered separate from the rarefied world of production, there’s nothing stopping you from using Hudson as a general purpose scheduler or server running within a production network.

If you have a requirement for scheduled services or if you need to perform a set of on-demand jobs in a production network, install Hudson and you’ve gained a friendly interface and a tool that can integrate with anything in the world. There’s nothing stopping you from using Hudson in production.

The Hudson Community at Eclipse

Hudson has an evolving community of developers and organizations interested in taking Hudson to the next level of stability and reliability. Following the creation of the Jenkins fork in early 2011, several members of the community decided to commit themselves to reconstituting the Hudson community and moving the project to the Eclipse Foundation. This move promises to create a more stable approach to open source governance while creating a level playing field for interested individuals and organizations.

Throughout its history the Hudson project lacked a formal structure and avoided process. Grown from a pet project, the governance of Hudson was ad-hoc. While this ad-hoc approach scaled for a few years, as more organizations decided to participate and contribute to the project the Hudson community identified a need for more formal procedures on issues such as release management, code provenance, and general technical direction. It is now the desire of the Hudson project to move toward a more formal process and structure with the end-goal of creating a healthy, open environment with well-defined rules, as well as a development process and release processes for building a high-quality and reliable continuous integration server.

Eclipse has a history of encouraging healthy environments for open source projects. It is an organization supported and respected by millions of end-users, thousands of contributors, and hundreds of active companies. In addition to being a great home for the Hudson project, Eclipse is also an important user of the software. Hudson has become an integral part of the development infrastructure at Eclipse, and the requirements of the Eclipse Foundation mirror the requirements of some of the largest enterprises in the world.

The Hudson Project

The main source of information about Hudson are the Eclipse Hudson website and the legacy website. The sites contain links to resources like the wiki, an issue tracker, the user forum, a few mailing lists, the source code and more. If you are looking for download Hudson or learn about participating in the, you can start with the Eclipse Hudson project’s web site.

At the time this document was developed, the Hudson project at Eclipse was focused on the following tasks:

  • Improving the core of Hudson by bolstering the test harnesses,

  • Creating a new performance harnesses allowing for more detailed performance assessment and testing.

  • Developing a fully automated test and release infrastructure

Some of the larger, medium-term goals of the Hudson project are:

  • Improving stability - The Eclipse project is investing in QA efforts to certify Eclipse to run on a set of standard platforms. Improving the reliability and stability of Hudson will enable more predictable behaviour for end-users and also enable an ecosystem of interested third-party providers of Hudson support services.

  • Improving performance - The project is focused on addressing performance, especially for organizations using Hudson to support large numbers of projects.

  • Improving Maven 3.x integration - Sonatype has contributed a completely reworked Maven 3 plugin which takes advantage of changes to Maven 3 which were made to increase the ease with which Maven could be integrate in IDEs such as Eclipse and CI servers such as Hudson.

  • Improve the UI - Prior to the migration to the Eclipse Foundation, the Hudson project had standardized on Jelly as a UI technology. The Hudson is currently focused on moving the UI system way from Jelly and toward a more modern approach to creating a solid, reactive user interface for Hudson.

  • Closer Integration for Core Plugins - One of the first steps of the Hudson project during the transition to Eclipse was to define a tiered set of Hudson plugins and establish a level of commitment and support to the most widely used plugins. It is the intention of the Eclipse project to increase the level of support and integration for these core plugins.

  • A standard OSGi Run-time Model based on Eclipse Equinox - Hudson’s legacy architecture was full of issues arising from the lack of a unified architecture. The Hudson project is work to move Hudson toward an OSGi model based on Eclipse Equinox. This will not only lead to a more stable CI server, it will make it easier to integrate and embed Hudson in systems like the Eclipse IDE and other, widely-used OSGi containers.

  • Support the a standard component model using JSR 330 - Early efforts were made to move the plugin API toward an approach compatible with JSR 330. This effort not only makes it easier to write and test Hudson plugins, it also aligns Hudson will the way that Java is developed in 2011 using frameworks and libraries such as Google Guice and VMWare’s Spring Framework.

  • Standard web services using JAXRS - Many of the plugins and core systems in Hudson are being migrated to a system that presents UI services as a collection of REST services. This foundational effort will set the stage for Hudson to move toward a richer, more reactive UI architecture possibly involving a migration to a SOFEA approach to user interface.

  • Backwards Compatibility - Despite this list of ideas and plans, the Hudson community is also focused on supporting existing plugins and Hudson APIs.

Hudson’s License

As Hudson has completed the transition to the Eclipse Foundation, the core of Hudson is covered by the Eclipse Public License version 1.0. The Open Source Initiative categorizes the Eclipse Public License as a "popular and widely used license with a strong community". The EPL is a limited copy-left license designed to be a "business-friendly" alternative to the GPL. More information about the Eclipse Public License can also be found on Wikipedia.

If you have any questions about the Eclipse Public License, the Eclipse Foundation also maintains a helpful FAQ about the license. A big reason for the move to the Eclipse Foundation was to make sure that the project was on solid ground for licensing issues. Eclipse takes intellectual property and code provenance very seriously and maintains a strict contribution review process to make sure that every project release complies with a set of licensing standards. If you download it from Eclipse, if it is stored in Eclipse’s source control systems, it is released under the EPL.

Note While the core of Hudson is licensed under the EPL, Hudson is a container for running various Hudson Plugins. These plugins may be covered by a variety of licenses, and if you are redistributing Hudson along with a set of 3rd party plugins, you should consult each individual plugin project to find a specific license.

Installing and Running Hudson

Hudson has a reputation for being both easy to install and very adaptable to running in a variety of environments. You can run Hudson as a stand-alone web application, or you can run Hudson within an existing servlet container. The Hudson project also maintains OS-specific packages for Redhat, Debian, Ubuntu, and other Linux distributions which make installing Hudson on these platforms almost effortless.

The following sections detail the installation process for Hudson. There are two different approaches to installing Hudson:

WAR File

The Hudson web site provides a Java web archive file (WAR) for download. This file can either be started directly or used in an existing Java servlet container or application server.

Native Package

Besides the web archive you can download packages for Hudson suitable for the use with the native package management systems on Ubuntu/Debian, Oracle Linux, Redhat/Fedora/CentOS and openSUSE.

It is a best practice to install Hudson as a service automatically started when an operating system boots. On a Windows machine this can be as straightforward as configuring a new Windows Service, and on a Linux machine this is as easy as dropping the appropriate script in /etc/init.d. The following sections outline the process for configuring Hudson as a service on various operating systems.

Prerequisites

While Hudson can run on a variety of machines under an almost infinite combination of JVMs, Operating System, and infrastructure. The Hudson project is targeting a set of standard operating systems and Java versions. This section outlines some of the expectations - the preconditions that are necessary to install and run a Hudson server.

Software Prerequisites

Hudson only has one prerequisite, a Java Runtime Environment (JRE) compatible with Java 6 or higher. Hudson is most often run with the JRE that is bundled with a Java Development Kit (JDK) installation. We recommend using the latest version of the JDK/JRE Java 6. If you are running on a modern Linux distribution such as Ubuntu, it is often possible to install the OpenJDK 6 project using a tool like apt-get (or yum on a Redhat distribution).

Download Oracle Java 6 JDK

The latest version of Oracle’s JDK 6 is the officially supported runtime. To download the latest release of the Oracle JDK, go to the Java JDK 6 Download Page, and download the latest Java 6 JDK.

Installing OpenJDK 6 on Linux

OpenJDK packages are available in both RPM and DEB format which should cover most Linux distributions. Installing OpenJDK 6 on your Linux machine can be done by following the instructions OpenJDK project site.

Hardware Prerequisites

As there is such a wide variety of Hudson deployments, from the Hudson server that runs a single project once every few days, to the Hudson server which serves as a master orchestrator of a hundred or more nodes in a massively distributed build grid, it is impossible to predict and recommend the necessary CPU power and disk space your particular installation will demand. Your own builds and your own systems will often dictate the specific hardware and network requirements for your Hudson instance.

What this section can do is provide a few recommendations that will help size and configure your infrastructure:

Network

If your Hudson server is very active you should make sure that there is sufficient bandwidth and low latency between your Hudson server and your source control system. Hudson is configured to periodically test the source control system and look for changes. In general, the critical components of your development infrastructure should be co-located with one another. Your CI server should be next to your SCM server. If your Hudson server is configured to automatically publish build artifacts to a repository manager, you should also make sure that the network connection between these two machines can support the expected level of activity.

CPU

In the absence of build activity, Hudson doesn’t consume very much in the way of CPU power. You can let Hudson run in the background, waiting for a build to trigger without having to worry about consuming more than a few processor cycles. With build activity, you should take the CPU requirements of your own development workstation and use that as a baseline for your Hudson server. Multiply the power you use as a single developer by the number of concurrent builds your Hudson server needs to handle. In general a two or four processor build machine with a powerful processors is a good starting point for a medium-sized work-group of 5-10 developers.

Memory

Compilers can often eat massive amounts of RAM. As with CPU configuration, take your own development workstation as a baseline and try to multiple that requirement by the number of expected concurrent builds. If your local build can easily run with 2 GB of RAM and you expect three concurrent build threads at any given time, then make sure that your Hudson instance can consume 6 GB of RAM on a server. You’ll have to use your own builds as a guide, but 4-8 GB of RAM should be adequate for a medium-sized work-group.

I/O

As with Memory requirements, builds, compilers, and tools like Maven and Ant tend to make disk drives go berserk with activity. If your builds are particularly I/O intensive, you are going to want to make sure that Hudson has sufficient local storage (or high-speed SAN storage). If you try to run a massive build job using an NFS mount to store output you are likely to see unacceptable build performance. Don’t "skimp" on hard drive quality or available storage space. I/O is often the primary gating factor in a large enterprise-class builds. Builds eat I/O.

Storage

You should be able to get off the ground with 5-10 GB, but once you start building your projects, you are going to want to preserve some build history. This build history can provide invaluable insight into the trends surrounding a particular build. If you were able to look at your project’s build history over a few weeks, you might notice that one developer in particular continues to break the build for your team. Alternatively, you can also configure Hudson to keep track of important metrics and trends such as test failures over time.

If you think that keeping build history around is important, you should configure Hudson with an appropriate amount of disk space. What this number is is heavily dependent on the size of your projects and the size of the generated binary artifacts. Larger projects with tens of thousands of lines of code can often get by with 60-100 GB, but the largest Hudson installations can easily reach a TB or more depending on the activity in a given development group.

Again, these recommendations come with a caveat: the authors of this document are not familiar with your application’s build. If your tests generate a huge amount of I/O activity or if your builds are particularly difficult to compile, you should use your best judgement. A good rule of thumb with Hudson deployments is to make sure that your Hudson server can satisfy a reasonable number of concurrent builds. Should it be able to run two builds in parallel? How about ten? This all depends on the size of your development and the frequency with which code changes are committed to source control.

Warning Continuous Integration servers drive quality, and if they are seriously under-powered they tend not to work. That tiny afterthought of a machine that management could spare for Hudson may end up taking several hours to run a build that takes minutes on your workstation. If software is something you produce, and if you value quality, you need to run a machine that will be able to keep up with your developers. If you treat the hardware running your CI system as an afterthought, it you can’t afford to invest in the necessary hardware, don’t be surprised if your quality, morale, and productivity take a nose dive.

Installing Hudson with the WAR File Distribution

The WAR file available for download on the Hudson web site is an executable WAR that has a servlet container embedded within it. Once downloaded and copied to the desired directory, you can start Hudson with the following command:

 java -jar hudson.war
Tip That’s it. The Hudson WAR ships with everything it needs to start itself.

This will start the servlet container as the current operating system user, inheriting access rights to the file system and so on. The Hudson home directory will be set to the .hudson folder in the user’s home directory. Once started the web-based Hudson user interface will be available at http://localhost:8080/hudson

figs/web/home-job-list.png
Figure 1. Hudson Application Window
Note This approach is suitable for testing and exploring Hudson, but it is not recommended to run Hudson as an executable WAR in production. Sure, it only took you a few seconds to download and start Hudson, but running dependable development infrastructure usually requires more than just a developer running "java -jar" from the command-line. If you really want to get serious about running Hudson, configure Hudson as a service on Windows or Linux.

Deploy Hudson to a Servlet Container

Conveniently the WAR file is suitable to be deployed in most commonly used Java servlet containers and application servers. The detailed process differs for these containers but in general the required steps are as follows:

Set up HUDSON_HOME

Hudson locates its configuration files and all other data in one folder and a collection of sub-folders to hold Job and build data. This folder should be configured by setting up an environment variable: HUDSON_HOME. The application will pick up this setting and use the specified folder to store job and configuration data.

Deploy to the server

Depending on the application server and your access rights you can deploy the WAR file via a web-based administration console or by copying the WAR into a deployment folder. The details of each servlet container and application server are beyond the scope of this book.

When using Hudson on your application server, you should ensure that the server is set up as an operating system service. The details of this setup widely vary between operating systems and application servers. The Hudson project provides helpful instructions for installing Hudson on Glassfish, WebSphere, JBoss, Jetty, Tomcat, Jonas, Weblogic and Winstone. More information about different containers and their specific needs in terms of installing and running Hudson is maintained on the Hudson wiki.

Note The recommended installation process is to install Hudson as a stand-alone service on a dedicated host using the operating system-specific packages supplied by the Hudson web site and documented in the following sections. If you choose to run Hudson in an application server or a servlet container, you may need to perform complicated configuration changes to ensure that Hudson adheres to a particular servers expectations.

Installing Hudson on Ubuntu/Debian

Hudson provides a package repository of deb files for users of Debian based distributions such as Debian, Ubuntu and others. This package will install Hudson and set up the CI server as a service.

Step 1: Install Java runtime

In order to fulfil the prerequisite of an installed Java runtime on a Debian based distribution it is best to install the meta package default-jdk, which will install OpenJDK. Either use a graphical user interface like synaptic or install from the command-line with apt-get using the following command.

sudo apt-get install default-jdk

If you prefer to use the Oracle Java runtime install it with the following apt-get command.

sudo apt-get install sun-java6-jdk
Step 2: Add Hudson repository URL to package management

The Hudson project hosts its packages in its own repository server. In order to use it you have to add its URL to your list of package sources with the following command.

sudo sh -c "echo 'deb http://hudson-ci.org/debian binary/' \
> /etc/apt/sources.list.d/hudson.list"

You can also add the APT line deb http://hudson-ci.org/debian binary/ in your GUI package manager as a repository URL. Future upgrades will not require this step to be repeated.

Step 3: Update the list of available packages

Once you’ve installed Java and added the Hudson repository URL you can update the list of available packages with the following command.

sudo apt-get update

This step has to be repeated whenever you want to check for the availability of upgrades. A common, best practice is to run yum update on a regular basis using cron this will alert you to updates as they become available.

Step 4: Install Hudson

Once your list of available packages is updated, you can install Hudson with the following command:

sudo apt-get install hudson

As the hudson packages are signed with a key that isn’t trusted by default, the installation process requires your confirmation. Once you have verified that you would like to install Hudson without verification, the installation process will then proceed to install and start Hudson. Your console output will look similar to the following output.

$ sudo apt-get install hudson
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following NEW packages will be installed:
  hudson
0 upgraded, 1 newly installed, 0 to remove and 4 not upgraded.
Need to get 38.8 MB of archives.
After this operation, 39.7 MB of additional disk space will be used.
WARNING: The following packages cannot be authenticated!
  hudson
Install these packages without verification [y/N]? y
Get:1 http://hudson-ci.org/debian/ binary/ hudson 2.0.0 [38.8 MB]
Fetched 38.8 MB in 39s (981 kB/s)
Selecting previously deselected package hudson.
(Reading database ... 180192 files and directories currently installed.)
Unpacking hudson (from .../archives/hudson_2.0.0_all.deb) ...
Processing triggers for ureadahead ...
ureadahead will be reprofiled on next reboot
Setting up hudson (2.0.0) ...
Adding system user `hudson' (UID 114) ...
Adding new user `hudson' (UID 114) with group `nogroup' ...
Not creating home directory `/var/lib/hudson'.
 * Starting Hudson Continuous Integration Server hudson  [ OK ]

As you can see from the output above, a hudson user was created. This user will run the Hudson server. The Hudson home folder is configured to point to the /var/lib/hudson directory. This is an important directory to remember, as it contains configuration, work-spaces, and other files related to your project’s builds.

Note Take note, if you are backing up Hudson, you will want to configure your backup systems to archive the contents of /var/lib/hudson. Everything interesting that relates to your projects is contained in this directory.
Step 5: Upgrade Hudson

To upgrade Hudson when a new release is available you would run the following apt-get command.

sudo apt-get upgrade

This will stop the running Hudson server, upgrade Hudson and restart the server. Prior to upgrading you should always backup your Hudson configuration and workspace data located in /var/lib/hudson.

Hudson File-system on Ubuntu

Running dpkg provides a list of the files installed by the Hudson DEB package. This list is a helpful guide for Hudson administrators as it helps locate interesting configuration files and directories you will need to know about when configuring and troubleshooting a Hudson installation.

$ dpkg -L hudson
/.
/var
/var/log
/var/log/hudson
/var/lib
/var/lib/hudson
/var/run
/var/run/hudson
/usr
/usr/share
/usr/share/doc
/usr/share/doc/hudson
/usr/share/doc/hudson/changelog.gz
/usr/share/doc/hudson/copyright
/usr/share/hudson
/usr/share/hudson/hudson.war
/usr/bin
/usr/sbin
/etc
/etc/apt
/etc/apt/sources.list.d
/etc/apt/sources.list.d/hudson.list
/etc/default
/etc/default/hudson
/etc/init.d
/etc/init.d/hudson
/etc/logrotate.d
/etc/logrotate.d/hudson

Starting and Stopping Hudson on Ubuntu

When you installed the Hudson DEB package on Ubuntu the installation process configured Hudson as a service. You can stop and start the service with the following commands:

sudo service hudson stop
sudo service hudson start

Alternatively, you can use the following commands:

sudo /etc/init.d/hudson stop
sudo /etc/init.d/hudson start

Hudson Log Files on Ubuntu

Following the Linux Standard Base conventions Hudson creates its log file in /var/log/hudson/hudson.log. This log file will be rotated automatically in the same way your syslog files are rotated on a nightly schedule.

This log rotation schedule can be configured by altering the configuration in /etc/logrotate.d/hudson.

Hudson Configuration on Ubuntu

The list of files installed by the Hudson DEB package reveal that a configuration file /etc/default/hudson was created. This file contains a number of configuration parameters that you might want to adapt to your needs. These include:

JAVA_ARGS

Used to increase the memory allocation for Hudson

HTTP-PORT

Sets the Hudson port to a default of 8080.

HUDSON_HOME

Defines the default location of Hudson’s working directory.

HUDSON_LOG

Defines the location of Hudson’s log file.

MAXOPENFILES

Defaults to 8192. This is an important configuration value for larger Hudson installations. If you are running out of file handles you can increase this limit here.

AJP_PORT

This configuration parameter is disabled by default, but if you are planning on exposing your Hudson service via a web server using mod_jk or mod_proxy_ajp, you can configure the AJP port in this configuration file.

JAVA

Defaults to /usr/bin/java. If you have a custom installation of Java, you can point your Hudson instance at a specific executable here.

HUDSON_USER

The DEB installer creates "hudson" user. This value is configurable in case you need to run Hudson under a different user.

Tip If you modify this file to suit your needs, you should add it to your backup strategy.

Installing Hudson on Redhat, CentOS, and Fedora

Oracle Linux, Redhat Enterprise Linux, CentOS and Fedora all use the same RPM package provided by the Hudson project. This package will install Hudson and set it up as a service.

STEP 1: Install Java runtime

In order to fulfil the prerequisite of an installed Java runtime on a Red Hat-based distribution it is best to install the meta package java, which will install OpenJDK, with your preferred package manager user interface. Either use a graphical user interface like Add/Remove Software or install from the command-line with the following command.

sudo yum install java
STEP 2: Add Hudson repository URL to package management

The Hudson project hosts its packages in its own repository server. In order to reference these packages you have to add the repository metadata to your list of package sources with the following command.

sudo wget -O /etc/yum.repos.d/hudson.repo http://hudson-ci.org/redhat/hudson.repo

Future upgrades will not require this step to be repeated.

STEP 3: Update the list of available packages

Once the prior steps are completed you can update the list of available packages in your graphical package manager or using the following yum command.

sudo yum check-update

This step has to be repeated whenever you want to check for the availability of upgrades. A suggested best practice is to run "yum check-update" on a regular basis and configure a system to notify you when your system is eligible for updates.

STEP 4: Install Hudson

Once your list of available packages is updated, you can install Hudson with

sudo yum install hudson

This command will require your confirmation. Once you’ve confirmed that you want to install Hudson, yum will then proceed to install and start Hudson. Your console output will look similar to the following output.

$ sudo yum install hudson
Loaded plugins: langpacks, presto, refresh-packagekit
Setting up Install Process
Resolving Dependencies
--> Running transaction check
---> Package hudson.noarch 0:2.0.1-1.1 will be installed
--> Finished Dependency Resolution

Dependencies Resolved

======================================================================
 Package        Arch            Version                 Repository      Size
======================================================================
Installing:
 hudson         noarch          2.0.1-1.1               test            37 M

Transaction Summary
======================================================================
Install         1 Package(s)

Total download size: 37 M
Installed size: 37 M
Is this ok [y/N]: y
Downloading Packages:
Setting up and reading Presto delta metadata
Processing delta metadata
Package(s) data still to download: 37 M
hudson-2.0.1-1.1.noarch.100% [=======] 953 kB/s | 37 MB         00:40
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
  Installing : hudson-2.0.1-1.1.noarch          1/1

Installed:
  hudson.noarch 0:2.0.1-1.1

Complete!
STEP 5: Upgrade Hudson

To upgrade Hudson when a new release is available run the following command:

sudo yum update

This command stops the running Hudson server, upgrade Hudson and restart the server. Prior to upgrading you might want to backup your Hudson data configuration located in /var/lib/hudson and owned by the hudson user.

Hudson File-system on Redhat

Looking at the list of files installed by the package we see that this RPM created the following files.

$ rpm -ql hudson
/etc/init.d/hudson
/etc/logrotate.d/hudson
/etc/sysconfig/hudson
/usr/lib/hudson
/usr/lib/hudson/hudson.war
/usr/sbin/hudson
/var/lib/hudson
/var/log/hudson

As part of the install a hudson user was created . This user will run the Hudson server. The Hudson home folder is configured to be located in /var/lib/hudson, which will contain configuration, work-spaces and so on and should be added to your backup strategy.

Starting and Stopping Hudson on Redhat

The install configured Hudson as a service so that you can stop and start the service with the following commands:

sudo service hudson stop
sudo service hudson start

Hudson Log Files on Redhat

Following the Linux standard base convention Hudson will create its log files into /var/log/hudson/hudson.log and the log files will be rotated on a nightly basis to preserve disk space.

Hudson Configuration on Redhat

This rpm command reveals that a configuration file /etc/sysconfig/hudson was created. It contains a number of configuration parameters that you might want to adapt to your needs. These include e.g. the HUDSON_JAVA_OPTIONS that can be used to increase the memory allocation for Hudson or the HUDSON_PORT parameter set to the common 8080. If you modify this file to suit your needs, you should add it to you backup strategy.

Installing Hudson on OpenSUSE

OpenSUSE uses a special rpm package provided by the Hudson project. This package will install Hudson and set it up as a service.

STEP 1: Install Java runtime

In order to fulfil the prerequisite of an installed Java runtime on openSUSE it is best to install the meta package java, which will install OpenJDK, with your preferred package manager user interface. Either use a graphical user interface like YaST or install from on the command-line with

sudo zypper install java
STEP 2: Add Hudson repository URL to package management

The Hudson project hosts its packages in its own repository server. In order to use it you have to add the repository meta data to your list of package sources with

sudo wget -O /etc/zypp/repos.d/hudson.repo http://hudson-ci.org/opensuse/hudson.repo

Future upgrades will not require this step to be repeated.

STEP 3: Update the list of available packages

Once the prior steps are completed you can update the list of available packages in your graphical package manager or with

sudo zypper refresh

This step has to be repeated whenever you want to check for the availability of upgrades. Common practice is for the update of the list to run automatically on a regular basis.

STEP 4: Install Hudson

Once your list of available packages is updated, you can install Hudson with

sudo zypper install hudson

This command requires you to confirm and will then proceed to install and start Hudson. Your console output will look similar to this

$ sudo zypper install hudson
Loading repository data...
Reading installed packages...
Resolving package dependencies...

The following NEW package is going to be installed:
  hudson

1 new package to install.
Overall download size: 37.1 MiB. After the operation, additional 37.1 MiB will be
used.
Continue? [y/n/?] (y):
Installing: hudson-2.0.1-1.1 [done]
Additional rpm output:
hudson                    0:off  1:off  2:off  3:on   4:off  5:on   6:off
STEP 5: Upgrade Hudson

To upgrade Hudson when a new release is available you would run the following command:

sudo zypper update

This command stops the running Hudson server, upgrade Hudson and restart the server. Prior to upgrading you might want to backup your Hudson data configuration located in /var/lib/hudson and owned by the hudson user.

The install configured Hudson as a service so that you can stop and start the service with the following commands:

sudo /etc/init.d/hudson stop
sudo /etc/init.d/hudson start

Following the Linux standard base convention Hudson will create its log files into /var/log/hudson/hudson.log and the log files will be rotated so you will no accumulate large log files using up disk space.

Looking at the list of files installed by the package

$ rpm -ql hudson
/etc/init.d/hudson
/etc/logrotate.d/hudson
/etc/sysconfig/hudson
/etc/zypp/repos.d/hudson.repo
/usr/lib/hudson
/usr/lib/hudson/hudson.war
/usr/sbin/rchudson
/var/lib/hudson
/var/log/hudson

This command reveals that a configuration file /etc/sysconfig/hudson was created. It contains a number of configuration parameters that you might want to adapt to your needs. These include e.g. the HUDSON_JAVA_OPTIONS that can be used to increase the memory allocation for Hudson or the HUDSON_PORT parameter set to the common 8080. If you modify this file to suit your needs, you should add it to you backup strategy.

As part of the install a hudson user was created . This user will run the Hudson server. The Hudson home folder is configured to be located in /var/lib/hudson, which will contain configuration, work-spaces and so on and should be added to your backup strategy.

Hudson Related Files and Directories

Depending on your installation method for Hudson using the standalone war, running it with an application server or using one of the native packages, all files required by Hudson will be located in different locations on the file system. In all cases however the main location for configuration of Hudson, plugins, builds and so on will be in your Hudson home directory.

It is defined as HUDSON_HOME and visible in the administration interface as Home directory in [fig-global-hudson-configuration]. With a native package install this would typically be /var/lib/hudson. When running Hudson in an application server or from the standalone war it typically is the .hudson folder in the home folder of the user running the application server or war file.

In addition you installation will include the Hudson war file itself as well as scripts for service start-up and log rotation. These vary depending on your install method in location as well as content. The sections for the native installer include details for these files. For application server based install or running from the standalone war file you will have set up these individually files yourself and therefore know about their location.

The Hudson home directory itself contains a number of files and directories that we will examine now.

The main Hudson configuration is contained in config.xml. It contains large number of configuration settings for Hudson itself including security and authorization details, views, nodes, JDK’s and other global parameters.

Further system-wide configuration specific to installed plugins are contained in numerous xml files, which represent a serialized form of the various plugin configuration settings. File names used vary widely, but include hudon.tasks.*.xml, hudson.plugins.*.xml, hudson.scm.\*.xml and others like maven-installation-descriptor.xml or rest-plugin.xml.

Plugins themselves are installed subfolder of the plugins folder. It typically contains the plugins as .hpi archives as well as extracted in a folders using the plugin name.

Any build tools like Apache Ant, Apache Maven or a JDK installed by one of the Hudson installers will be installed their own directories in the tools folder.

The fingerprints folder contains the fingerprint records created by build artifacts created and tracked by Hudson.

The users folder contains subfolders for each user of Hudson or committer on the projects built in a config.xml file, that contains email configuration as well as configured views and other user specific data.

The userContent folder can contain static content that Hudson will serve in the userContent context. It can be used to make e.g. software installation packages or web site content available to Hudson users without requiring a separate web server.

Beyond all the global configuration described so far all the job related configuration and data is stored in individual subfolder of the jobs folder. Each project has a folder using the project name as configured in [section-configuring-general-project-settings]. The config.xml file within this folder contains all project specific configuration parameters. The workspace contains the project as currently checked out from the used SCM. If the Maven 3 integration is set to use a private repository, it will be located in the .maven/repo folder in the workspace. The individual build results, logs and artifacts are stored in directories with date and time stamps as folder names within the builds folder. In addition symlinks with build numbers are created to point to the time stamped folders.

Backing up Hudson Data

A full backup would be the complete content of your Hudson home directory as explained in [ci-sect-directories] and any customized files for service start-up and log rotation.

This folder can also be used to migrated your Hudson instance to a different server by simply copying it over after installing Hudson on the new machine.

For a limited backup you could e.g. omit some of the build history of various jobs or potentially large Maven repositories for the various builds.

Tip The JobConfigHistory Plugin, the thinBAckup Plugin as well as the Backup Plugin can be used to simplify your backup strategy, if you want to reduce the need for external tools. Some users are using a version control system like Git or Subversion to track changes of the Hudson home directory. You could even use a Hudson job to e.g. do regularly scheduled commits of config changes.

Upgrading Hudson

Since Hudson separates it’s configuration and data storage from the application, it is easy to upgrade an existing Hudson installation. After a full backup of all configuration and data, you should be ready to proceed after notifying your users about potential down-time. You might also want to disable all jobs before proceeding.

For native package users this will be handled transparently with their package management system. For WAR file based installs, you only have to remove the old version WAR and replace it with the new version in your application server.

Typically upgrading Hudson should include upgrading any used plugins as well to avoid incompatibilities.

Running Hudson Behind a Proxy

If you installed Hudson as a stand-alone application, Hudson is running on a high-performance servlet. From a performance perspective, there is no reason for you not to run Hudson by itself without a proxy. Yet, more often than not, organizations run applications behind a proxy for security concerns and to consolidate applications using tools like mod_rewrite and mod_proxy. For this reason, we’ve included some brief instructions for configuring Apache HTTP. We assume that you’ve already installed Apache 2, and that you are using a Virtual Host for www.example.com.

Let’s assume that you wanted to host Hudson behind Apache HTTP at the URL http://www.example.com. To do this, you’ll need to change the context path that Hudson is served from.

  1. Need to explain how to run Hudson in the root context here

  2. Restart Hudson and verify that it is available on http://localhost:8080/.

  3. Clear the Base URL in Hudson Application Server Settings in the administration interface.

At this point, edit the HTTP configuration file for the www.example.com virtual host. Include the following to expose Hudson via mod_proxy at http://www.example.com/.

ProxyRequests Off
ProxyPreserveHost On

<VirtualHost *:80>
  ServerName www.example.com
  ServerAdmin admin@example.com
  ProxyPass / http://localhost:8080/
  ProxyPassReverse / http://localhost:8080/
  ErrorLog logs/example/hudson/error.log
  CustomLog logs/example/hudson/access.log common
</VirtualHost>

If you just wanted to continue to serve Hudson at the /hudson context path, you would include the context path in your ProxyPass and ProxyPassReverse directives as follows:

ProxyPass /matrix/ http://localhost:8082/matrix/
ProxyPassReverse /matrix/ http://localhost:8082/matrix/

Apache configuration is going to vary based on your own application’s requirements and the way you intend to expose Hudson to the outside world. If you need more details about Apache httpd and mod_proxy, please read the documentation on the project website.

Hudson Configuration

To configure Hudson, click on the Manage Hudson link in the left-hand navigation menu, which will display the screen shown in [fig-config-manage-hudson]. This chapter will focus on the Configure System section.

figs/web/manage-hudson.png
Figure 2. Managing Hudson

Depending on the plugins installed and activated on your Hudson system, different sections will be available in the system configuration section. These will either be explained below or with a plugin-specific section. For example the source code management-related global configurations for the different SCM systems is available in [chapter-source-control].

Global Hudson Configuration

The first section in the Configure System screen contains options that allow you to configure global Hudson configuration attributes. This section is shown in [fig-global-hudson-configuration].

figs/web/global-hudson-configuration.png
Figure 3. Configuring Global Hudson Configuration
Home Directory

This parameter displays the absolute installation path of the currently running Hudson system. It is not a runtime configurable parameter. It is set by the server on start-up. By default it will be the value of the HUDSON_HOME environment variable or the .hudson folder in the home directory of the operating system user running Hudson. The value is displayed here to allow the administrator to verify the correct setting.

System Message

This message is displayed by Hudson in the main screen above the list of projects. It can be used as a welcome message or to e.g. broadcast upcoming maintenance to users of the Hudson instance via the user interface. It supports plain text as well as HTML snippets for formatting and enriching the message with dynamic content.

# of Executors

This parameter controls the number of concurrent builds Hudson is configured to run. Optimal values in terms of performance will depend on the number of CPUs, IO performance and other hardware characteristics of the server running Hudson as well as the type of builds configured to run. A good starting point for experimentation is the number of CPUs.

Quiet period

A Quiet Period as specified in this configuration causes Hudson to wait the specified number of seconds before a triggered build is started. If your Hudson project is constantly "flapping" (switching between failure and success frequently), you may want to set the Quiet period to achieve more build stability. Another scenario this can be helpful is when large commits to your source control system are typically carried out in multiple smaller commits within a short time frame, so that the committer has a chance to get everything in without a build kicking off straight after the first commit causing a build failure. Setting this number to a large amount can generally reduce the number of builds running for this project, which will reduce the overall load for your Hudson server.

SCM checkout retry count

The SCM checkout retry count determines the number of attempts Hudson makes to check out any updates when polling the SCM system for changes and finds the system to be unavailable.

Enable Security

The Enable Security check box switches on the security system that will require user-name and password for any access to run builds or change configurations of Hudson and build projects. A large number of configuration options and security providers can be used and more information can be found in [chapter-security]

Prevent Cross Site Request Forgery exploits

This feature will enable improved security against Cross Site Request Forgery exploits and is recommended to be turned on when your Hudson instance is available to the public Internet. On the other hand it can be necessary to have this feature disabled, when your Hudson web interface is embedded in a dashboard type interface that also contains web content from other domains or even only internal server names or sub networks. In general it will not be necessary to enable this feature on an internal network, where only trusted parties have access to Hudson.

Help make Hudson better…

By selecting this feature to be enabled you agree for anonymous usage statistics about your Hudson installation to be created and securely sent to the Hudson development team and made available to the user community. The data sent consists of

  • the Hudson version you are using

  • operating system, JVM and number of executors for your master Hudson and any slaves being used

  • the name and version of all activated plugins

  • the number of each project type configured to run

  • HTTP information as provided by your Hudson instance

Global Properties Configuration

The global properties configuration allows the definition of key-value pairs that are exposed to all running builds as environment variables. Simply select the check box Environment Variables and add the desired name and value for the property in the interface displayed in [fig-configure-global-properties].

figs/web/configure-global-properties.png
Figure 4. Configuring global properties

Depending on the build system used they can be picked up with variables are populated by Hudson automatically. These include job-related ones like JOB_NAME, BUILD_TAG or BUILD_NUMBER, Hudson node-related ones like NODE_NAME or more global ones like JAVA_HOME. A comprehensive list is available at env-vars.html on your Hudson server e.g. http://localhost:8080/env-vars.html as linked from the in-line help for the properties configuration.

Configuring JDK Installations

Hudson can support one or more JDK installations used for running your builds. Setting up multiple JDK installs allows the configuration of different projects being built by different Java versions in separate jobs. You can use this to ensure e.g. that builds as well as test suites run fine on an older Java version to ensure compatibility. Another application would be to run with JDK versions supplied by different vendors.

The most common configuration of a JDK is to point to the already installed instance as used for running Hudson itself. This can be achieved simply by supplying a name like Open JDK 6 in the Name input field and the absolute path in the JAVA_HOME input field in the screen as shown in [fig-using-jdk-config].

figs/web/configure-jdk.png
Figure 5. Configuring JDK Installations

Furthermore it is possible to configure a JDK to be installed automatically by specifying a name as before and then selecting the Install Automatically check box. This exposes a drop-down labelled Add installer which lets you choose from the options Install from Oracle, Extract *.zip/*.tar.gz and Run Command as visible in [fig-using-jdk-config].

Warning The automatic installation from Oracle is currently disabled, while Oracle implements a web service for JDK installation.

All the automatic install configurations cause Hudson to wait for the first build, which is configured to use a named instance of the JDK to initiate the JDK installation. The JDK will be installed into a folder in the tools directory in Hudson home using the tool name specified as the folder name.

The option Install from Oracle brings up a drop-down to choose the version as well as a check box that needs to be clicked to the Java SE license agreement.

If you select to use Extract *.zip/*.tar.gz as shown in [fig-extract-archive-installer] you will be able to configure a Label, the Download URL for binary archive and the Subdirectory of extracted archive.

figs/web/extract-archive-installer.png
Figure 6. Extract *zip/*.tar.gz archive Installer Configuration

If you specify a label, only Hudson nodes with the same label will use this installer. By using different labels it is possible for example to get the same tool installed on different nodes with different operating systems from different automatic install setups. The download URL specifies the full URL from which the JDK will be downloaded. The actual download is run off the Hudson master, so that any Hudson nodes that need the JDK installed do not need to have access to the URL location. After successful download the JDK will be installed in the specified sub directory in the tools folder of the Hudson home directory.

figs/web/run-command-installer.png
Figure 7. Run Command Installer Configuration

The last automatic installation option is the Run a command option displayed in [fig-run-command-installer]. The Label options works the same as for the archive extraction based install. The Command input allows you to specify the shell command to execute on the node for the install. Typically this is some package management invocation. The resulting tool directory has to be specified in the Tool Home input box.

Once more than one JDK is configured in the global settings, each project configuration has an additional drop-down, which allows the selection of the JDK to be used to build the project and is visible in [fig-extract-archive-installer]

Configuring Ant Installations

In a similar fashion to the JDK install Apache Ant can be installed in multiple versions to be available for your Hudson configured builds. The default configuration is to supply a name like Apache Ant 1.8.2 for the Ant installation and a value in the ANT_HOME input that is defined by the absolute path to the folder containing your pre-existing local Apache Ant install e.g. /opt/apache-ant-1.8.2

Using a pre-installed Ant requires manual install or the use of your operating system package management system, a provisioning system or as part of a virtual machine image management. To avoid this need Hudson can install a required Apache Ant version automatically when needed.

The simplest way to achieve this is to select the Install automatically check box and select Install from Apache and choose the desired version from the drop-down.

Similar to the JDK installation from Oracle it is possible to use Install from Apache to get Ant installed into a sub-directory of the tools folder in Hudson home. The options to install from an archive or by running a command are available as well and work in the same way as for JDK installs. A use case for an install from a file would be a custom Ant distribution with libraries for in-house tasks and maybe Ant contrib included as documented in detail in [chapter-ant]

Configuring Maven Installations

One of the main uses cases for Hudson is building projects with Apache Maven. As explained in more detail in [chapter-maven] the preferred way to build Maven projects is the Maven 3 integration. It comes with a bundled Maven 3 install so you do not actually need to install Maven 3 at all to get started. However if you want, you can install additional Maven 3 installs with the user interface displayed in [fig-configure-maven-3-installation].

figs/web/configure-maven-3.png
Figure 8. Configuring Maven 3 Installations

The legacy Maven project type and Maven plugin use a separate installer as displayed in [fig-configure-maven-installation]. In addition to the same features as the Maven 3 installer it can be configured to download a Maven version from the Apache web site when required.

figs/web/configure-maven.png
Figure 9. Configuring Maven Installations

Both the Maven 3 and the Maven installation work in a similar way to the JDK and Ant installation options:

Use an existing installation

Specify a Name and add the path to your Maven install in the MAVEN_HOME input control.

Automatically install from Apache

Select the Install automatically check box and Install from Apache in the drop-down and choose the Maven version, you wish to install. This option is only available for the Maven installation.

Automatically install from an archive file

Select the Install automatically check box and Extract *zip/*.tar.gz and configure the installation as documented in [section-configure-jdk]

Automatically install via a command

Select the Install automatically check box and Run Command and configure the installation as documented in [section-configure-jdk].

In general we recommend that you run your build using the latest Maven 3.0 release. With multiple Maven installations configured a drop down in the project build step configuration will allow you to choose the desired Maven version. [chapter-maven] provides an in-depth documentation for using Maven with Hudson.

Maven 3 Builder Defaults

The Maven 3 integration allows for a set of default values to be defined that are used when a new build step for invoking Maven 3 is added. These values can be defined in the section Maven 3 Builder Defaults in the global Hudson configuration here. The individual fields and their purpose and usage are documented in [section-maven-3-build-configuration].

Configuring the Shell Executable

Hudson allows for the ability to configure shell builds. If you have a build that requires the execution of shell scripts Hudson will by default execute+/bin/sh+. For more complex builds scripts running on different *nix environments, this can cause problems. /bin/sh often symlinks to a concrete shell like bash, ash, zsh or ksh. This setup of a specific shell will change from operating system to operating system as well as from user to user. If your scripts depend on a specific shell you should therefore specify your default shell in this input to e.g. /bin/bash. In a similar way you can add the path to a cygwin install of e.g. bash on your Windows server to run unix scripts as part of your build.

Configuring Shell Executable

figs/web/ci-using-shell-execute.png

Configuring E-mail Notification

Notification of build results and email-based notification specifically is a core feature of a continuous integration server. This configuration section as displayed in [fig-configure-email-notification] allows you to configure the SMTP-related settings to connect to the server and send the emails.

Tip In general it can be advantageous to configure all email recipients in Hudson as mailing list addresses. Combined with a mailing list management system available to your potential recipients e.g. development and QA team members, this setup allows users to join any mailing list and therefore notifications for specific jobs without any configuration changes on Hudson.
Configuring Email Notification

figs/web/configure-email-notification.png

The following options can be configured:

SMTP Server

The SMTP server configuration is typically the IP number of the mail server or a fully qualified name including the domain e.g. smtp.example.com . If the mail server is reachable by host name or some alias e.g. hermes from the Hudson server you can use it as the SMTP server configuration.

Default user e-mail suffix

This suffix is appended to the Hudson user names used to log in to Hudson and the result can be used for e-mail notification. E.g. if the Hudson instance runs for example.com you could supply the suffix of @example.com. A Hudson user with user name jane.doe would then receive email notifications at the email jane.doe@example.com. This can be especially useful with security setups using an identity management system like LDAP for Hudson access as well as email address setup as documented in [chapter-security].

System Admin E-Mail Address

This is the email address used as the email sender in any E-mail notification sent by the server. When configuring this email you should either ensure that emails sent back as a reply are monitored by somebody or bounced by the server with some meaningful error message.

Hudson URL

The Hudson URL value will be used in the email notifications sent out to provide links to build results and so on. Provide a URL that will be valid for the audience of your notifications. If all recipients will be on an intranet or VPN you can use a non-public URL or IP number.

In addition to basic SMTP configuration parameters, you can click the Advanced Options button for further configuration that allows you to send email via servers that require authentication. Most SMTP servers will require at least user name and password to be accessed.

Use SMTP Authentication

Clicking on the check box will reveal User Name and Password input fields. Depending on the server configuration your user name will be just the log-in name or the full email address or either.

Use SSL

Select this check box if your SMTP server supports connecting with SSL activated.

SMTP Port

This configuration allows you to specify a custom port for the communication with mail server. If the field is left empty the default ports are used. These are 25 for SMTP and 465 for SSL secured SMTP. It is a common practice to configure a different port, so be sure to check with the administrator of the mail server what port you should be using.

Charset

The Charset configuration determines the character set used for the composed e-mail message.

Test configuration

Pressing this button will execute the current configuration for sending emails. Depending on your configuration and network setup you should receive an email after a short while.

E-mail Notification Via Gmail

In order to use GMail to send your emails you will need to configure the SMTP server to smtp.gmail.com. In addition you will have to have a Gmail account and provide the GMail e-mail address, or any other email address configured to be accepted in your Gmail account, as the User Name and configure the Password.

Troubleshooting E-mail Notification

One of the common problems for build server notification emails not being received are spam filter settings on the server and/or client side of the recipient. Most spam filter systems will allow you to access a list of filtered message and configure a white list of senders. Adding the System Admin E-mail Address to the white list will ensure that your build notifications reach you.

Managing Maven 3 Configuration

The Maven 3 integration of Hudson provides you with the ability to manage custom Maven configuration files directly through the Hudson user interface. You can manage:

  • Maven Settings Configuration

  • Maven Toolchains Configuration

Opening the Maven 3 Configuration Page

To open the Maven 3 Configuration page, click on Manage Server in the left-hand Hudson menu, and then select the Maven 3 Configuration item shown in [fig-config-manage-hudson].

Once you select the Maven 3 Configuration option, you will see the page shown in [fig-manage-mvn-3-configurations]. If you have already configured Maven Settings or Maven Toolchains configuration documents they will appear in the list of documents shown on this page. If you have not configured any Maven configuration documents, you will see the empty configuration screen shown in [fig-manage-mvn-3-configurations].

figs/web/manage-mvn-3-configurations.png
Figure 10. The Maven 3 Configuration Page

To create a new Maven 3 Configuration document, click on the Add button. This will create a new configuration document and display a form that will allow you to name the document, describe the document, select a document type, and supply configuration content for a configuration document.

To remove an existing document, select the document from the list of documents shown and click on the Remove button. This will load a confirmation dialogue. If the action is confirmed, the document will be permanently removed from your Hudson instance.

Click the Refresh button in the interface to reload the Hudson configuration and display any configuration documents which may have been altered since you first loaded this page.

Managing Maven 3 Settings Configuration

To create a new Maven 3 Setting configuration file which can be referenced by a Hudson Maven 3 build step, click on the Add button as shown in [fig-manage-mvn-3-configurations]. Clicking on Add will display a form containing the ID, Type, Name, Description, and Attribute fields as shown in [fig-manage-mvn-3-settings]. Select SETTINGS for the Type field.

figs/web/manage-mvn-3-config-settings.png
Figure 11. Managing Maven 3 Settings in Hudson

The sample Maven 3 Settings configuration shown in [fig-manage-mvn-3-settings] define a General Maven 3 Settings file which configures all Maven 3 builds to read artifacts from a corporate Nexus repository. This sample XML was copied from the Maven 3 Settings example in the Sonatype Nexus book and customized to reference a hypothetical server running on nexus.sonatype.org:8081.

Usage of the Maven 3 Settings configuration file in a Hudson job as well as Maven toolchains is documented in [section-maven-3-build-configuration].

Configuring Global and Individual Project List Views

Running a Hudson server or grid with many projects can make the list of configured jobs very long and therefore make it difficult for users and administrators to gather the information they need at a glance and find their way to the job they are interested in. To provide this needed ease of access Hudson supports the addition of globally visible as well as user specific views to the main page displayed in [fig-ci-quickstart-app-win].

To add a new view simply click the + button beside the default list called All on top of the job list. If this button is not visible you do not have the access right to create views. Creating a view this way will make it globally visible to any user.

Logging in as a specific user shows the My Views option in the left hand navigation menu. When you select this option the bread crumb navigation will contain your user name and the My Views option. Pressing the + button on the main job list now will create a personal view only visible to the current user when logged in.

Each view can be given a description by clicking the edit description on the right side above the job list.

When adding a new global view as displayed in [fig-configure-new-global-view] you have to provide a name and then select what type of view you want to add. You can either add a My View, which will display all jobs the current users has access to or you can add a List View, which is a highly configurable list of job types. The different configuration options are documented below.

figs/web/configure-new-global-view.png
Figure 12. Adding a New Global View

After you have created the view you can configure the main filter properties displayed in [fig-configure-view-main], configure, add and delete job filters as displayed in [fig-configure-view-filters] and add and delete columns for the list view as displayed in [fig-configure-view-columns].

figs/web/configure-view-main.png
Figure 13. Main Properties for Adding a New View

Besides the name provided at creation you can add a description that will be displayed above the list of jobs and below the title of the view. It can use HTML for e.g. hyperlinks to other related resources. The Filter build queue option causes Hudson to only show jobs from the view in the build queue. The Filter build executors option causes Hudson to only show build executors that could execute shows from this view.

The Job Filters configuration below as visible in [fig-configure-view-filters] shows the Status Filter, a list of all jobs and allows the configuration of a regular expression for inclusion of jobs on the list view. The regular expression is applied to the job name.

figs/web/configure-view-filters.png
Figure 14. Configuring View Filters

The Status Filter has the option to use all selected jobs or only enabled or disabled builds from the list below or the result of the regular expression configured. The Jobs list itself is an alphabetically sorted list of all jobs configured with a check box for each job that you potentially want to include in the view. As an alternative to manually selecting jobs from the list you can configure a regular expression to match on the job names. With a good naming convention for the jobs this can be a good way to build the list. An example could be naming all release build jobs x-y-z-release or naming all plugin builds Plugin-x and then using a regular expression like .*-release or Plugin-.* to select them.

In order to have access to more powerful configuration options for your list views you have to install the View Job Filters plugin. It will hook into the Job Filters section creating the Add Job Filter button and providing the filters documented in the following.

The filters will be applied in the order in the configuration screen. Each filter has a Match Type drop down selector that allows you to include matched or unmatched jobs as well as exclude matched and unmatched jobs from further filtering.

A myriad of combinations is possible allowing you to implement easy access to all your builds for all your users catered to their varying needs

With the Build Statuses filter displayed in [fig-configure-view-filters-build-status] you can include or exclude builds that are currently building, that have never been built or that are currently in the build queue.

figs/web/configure-view-filters-build-status.png
Figure 15. Configuring the Build Status View Filter

The Job Statuses filter in [fig-configure-view-filters-job-status] allows you to combine Stable, Failed, Unstable, Aborted and Disabled statuses to create a filter for including or excluding jobs from your view.

figs/web/configure-view-filters-job-status.png
Figure 16. Configuring the Job Status View Filter

Similarly the Job Type filter in [fig-configure-view-filters-job-type] can be used to include or exclude based on the job being a free-style project, a Maven2/3 project, a multi-configuration project or a monitor of an external job.

figs/web/configure-view-filters-job-type.png
Figure 17. Configuring the Job Type View Filter

The Other Views filter in [fig-configure-view-filters-other] has a selector for the other view which can be used for including or excluding jobs to the current view being configured. This allows you to easily create negations of other views e.g. all non release builds, or all non plugin builds or simply create a finer grained view of a different view. E.g. you could easily create a view of all plugin builds that are currently with the job status Failed using a combination of the Other Views and the Job Statuses filter. Another good use case for this filter is to use multiple Other Views filters to aggregate the content of a number of other views.

figs/web/configure-view-filters-other.png
Figure 18. Configuring the Other Views Filter

The Parameterized Jobs Filter in [fig-configure-view-filters-parameterized-jobs] can be used to define a Name and Value that will match against the build parameters.

figs/web/configure-view-filters-parameterized-jobs.png
Figure 19. Configuring the Parameterized Jobs View Filter

The Regular Expression Job Filter displayed in [fig-configure-view-filters-regex] can be used to run a pattern matching against Hudson job name, job description, job SCM configuration, email recipients or Maven configuration.

figs/web/configure-view-filters-regex.png
Figure 20. Configuring the Regular Expression Job View Filter

The SCM Type filter allows you too filter based on the SCM used for your builds.

figs/web/configure-view-filters-scm-type.png
Figure 21. Configuring the SCM Type View Filter

The Unclassified Jobs view filter can be used to show all jobs that do not show up in any other view.

figs/web/configure-view-filters-unclassified.png
Figure 22. Configuring the Unclassified Jobs View Filter

The User Permissions view filter can be used to only show jobs with a specific permission for the currently logged in user. A drop down allows you to define the matching used and the permissions are displayed below as check-boxes.

figs/web/configure-view-filters-user-permissions.png
Figure 23. Configuring the User Permissions for Jobs View Filter

The All Jobs filter for simply adding all jobs and then using further filters to reduce the matches ending up in the view list.

The section below the Job Filters allows you to configure the columns used in the list view. Add and delete columns with the provided buttons as displayed in [fig-configure-view-columns]. To change the order of columns you can drag the title and drop them in the desired position.

figs/web/configure-view-columns.png
Figure 24. Configuring View Columns

When you are logged into Hudson as a user you can also create a different view type called My View. It automatically contains all projects you currently have access to.