The Hudson Book

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.

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.

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.

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.

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.

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 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:

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

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.

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.

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:

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

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:

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.

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.

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

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.

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.

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.

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.

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.

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.

Future upgrades will not require this step to be repeated.

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.

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.

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.

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

Future upgrades will not require this step to be repeated.

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.

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

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:

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

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.

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.

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.

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.

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.

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/.

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:

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.

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].

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].

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.

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].

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].

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.

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.

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]

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]

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].

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.

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

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.

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].

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.

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.

The following options can be configured:

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.

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:

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.

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].

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

Hudson exposes various RSS feeds that you can subscribe to in your favourite RSS feed reader. The server needs to be reachable via http by your RSS reader for this feature to be usable.

Various pages in the web interface feature RSS buttons in the bottom left corner as visible in [fig-ci-quickstart-app-win].

Out of the box Hudson has no security enabled. To enable security, check Enable security in the global configuration of Hudson as displayed in [fig-global-hudson-configuration]. Once you have enabled security you will be able to set up your desired security settings with the options visible in [fig-security-overview] and documented in this chapter.

With security enabled, Hudson supports the following authentication security realms out of the box. Further options are available as plugins.

Access-control schemes available are:

These security options can be seen in [fig-security-overview] and are documented in detail below.

The configuration of the security realm allows you to define where user names and passwords are stored and administered. Depending on your deployment it can be useful to tie into already existing systems or run a separate realm for Hudson.

Once you’ve selected a security realm for authorization you’ll know how users and groups are created and what has to be done for a user to be able to log in to Hudson. As a next step you need to decide on your Hudson instance’s approach to access-control. Access control settings determine what a user can do and see once they are logged in.

To get a list of installed plugins, click in the Installed tab. This will display a list all of the Hudson plugins currently installed on your instance of Hudson system.

The Enabled check box allows you to activate and deactivate specific plugins. After plugin updates your old plugin version will remain accessible and you can downgrade to the older version by pressing the Downgrade to x.y.z button. The pinned column will then be marked for this plugin so that automatic updates will not occur until you unpin the version. Any changes will require you to restart Hudson by clicking the "Restart once no jobs are running button" as displayed in [fig-plugin-mgt-progress].

This list of available plugins includes hundreds of useful utilities, tweaks, and feature sets which extend the core feature set of Hudson. The list is separated into topics and contains a short description for each plugin as well as a link to the plugin web site. In order to install a plugin, simply select the check box in the plugin row, press the Install button on the bottom of the list. This will redirect to a progress reporting page. After a success message you will have to restart Hudson by clicking the Restart once no jobs are running button for the new plugin to be available.

Hudson regularly checks an available list of Hudson plugins on the Hudson web site and will notify if an update becomes available. To see if any updates are currently available click on the Updates tab in the Manage Plugins screen. Plugins eligible for an update will be displayed next to the available update version and the version which is currently installed. To update a plugin select the check box in the Install column and press the Install button on the bottom of the list. This will redirect to a progress reporting page. After a success message you will have to restart Hudson by clicking the "Restart once no jobs are running" button for the new plugin to be available.

The Advanced tab as displayed in [fig-plugin-mgt-advanced] allows you to configure the proxy settings for Hudson to be able to connect to the plugin repository on the Hudson web site, upload Hudson plugin files (*.hpi) manually, and specify the URL for a custom update site.

Hudson retrieves a list of plugins and downloads plugins over the public Internet. If your server is behind a proxy server, you will need to configure the proxy settings. Supply the necessary values to connect to your internal proxy in the Server and Port fields. The No Proxy for field allows you to exclude host names from proxying by adding them to a comma separated list. If your proxy server requires authentication you will have to select the Proxy Needs Authorization check box and provide the User name and Password.

Hudson plugins are distributed as .hpi files and the the Advanced administration section allows you to upload them with a file chooser. This feature is especially useful for installing custom developed plugins or commercially distributed plugins that are not available on the update site. You can also use it to install plugins you build from source during development or when helping by contributing fixes to open source plugins.

Instead of using the public update site on the Hudson web site you can host your own plugin repository and you can then add the URL in the available input field. This approach is useful if you need to maintain a secured Hudson instance that cannot be affected by the day to day changes on an external Hudson plugin update site. If you use this option, you can point your Hudson instance at a local copy of the public Hudson plugin update site and strictly control the changes that are visible to your Hudson instance.

To create a new Hudson project, click on New Job in the left navigation menu, which will display the form shown in [fig-using-new-project].

The most common way to create a new job using Hudson is to select "Build a free-style software project". If you are creating a project that is similar to an existing Hudson build, you may also choose "Copy an existing job" and then type in the name of the Hudson job in the Copy from text field. Once you have made your selection and provided a name for the new job, click on OK to continue.

You can also configure Hudson to Monitor an external job which can then trigger and affect other jobs. The last job type supported by Hudson is to Build a multi-configuration project, which can act like a container for a variety of different job executions.

Once your job has been created, you will see a screen similar to the one shown in [fig-using-new-project-result], depending on your job type selection. You can now proceed to configure your project. If you need to change any of these settings at a later stage, navigate to a particular Hudson Project’s Summary page by clicking on the name of the project on the main Hudson page. Once you are on a Hudson Project’s Summary page, click on Configure in the left-hand navigation to load the Project Configuration screen.

Independent of the job type you selected you will be able to configure a few common settings separated in the following sections:

Depending on the job type you choose additional sections may be present in the project configuration screen. The following sections provide an overview of some common project configuration options.

In addition to the common project configurations we discussed prior, a free-style Hudson project has a section for the build definition that allows you to add individual build steps. Press the Add build step button in the Build configuration section to set up one or multiple steps that define your build with the choices displayed in [fig-freestye-add-build-step] and documented below.

Multi-configuration projects have to be configured as such when initially creating the project as visible in [fig-using-new-project]. A multi-configuration project is a free-style project with additional parameters called axis defined. These axis values create a matrix of possible combinations. Each of these combinations is a possible build execution with the specific combination of parameters passed to the build.

[fig-configure-matrix] and [fig-configure-matrix-axis-config] show the general Configuration Matrix section as well as an example of some axes defined. A pre-configured axis available offers the choice of JDK used for the project build. In the example two further axes are defined. For for a database backend used for the build and another for the type of build to execute. Axis can be added by creating the Add axis button and removed with the Delete button.

All these axis values create a configuration matrix on the project overview page as visible in [fig-configure-matrix-axis-display].

The most important configuration steps is to define the axes that you will use for your project. The user-defined axis definition allows you to define a name and multiple values. These values will be passed to your build execution as variables and you have to ensure in your build configuration that they are e.g. used as Maven profile names in the a build step or passed in as properties and picked up to select the correct database connection. The values have to be separated by white-space in the values input field.

In addition you can configure the following settings.

In order to use Apache Maven for your project build you will have to configure one or more installs, as documented in [section-configure-maven]. Among the many factors that influence your choice of installation method you might want to consider the following:

With assessing these influencing parameters you will be able to derive a strategy for your Maven install(s), that will work across the different machines in your build cluster and for all your projects. This strategy can potentially involve different installation methods. When using the recommended Maven 3 integration no Maven install is necessary, since a Maven 3 install is embedded with the plugin. Otherwise a minimal setup of one Maven install can be used to set up your first project, that is built with Maven on Hudson.

The recommended way to configure a Maven build on Hudson is to create a free-style software project as documented in [chapter-build-creation] and then creating one or more build steps that Invoke Maven 3. More details on the specific configuration options and more can be found in [section-maven-3-build-configuration].

If you require Maven 2 for your build for some legacy reason, even though Maven 3 is a higher performing, drop-in replacement you can fall back to using the Invoke Maven 2 (Legacy) build step documented in [section-maven-2-build-configuration]. Even though this option exists, we recommend moving forward and migrating to Maven 3 and the Maven 3 build step.

Finally your Hudson install may contain a separate project type labelled Build a Maven 2/3 project (Legacy) available when creating a new project. This feature has numerous issues with the use of different Maven versions and use cases, especially Maven 3, and is not supported in Hudson. We recommend not to use this job type. If you do not need this job type anymore after migrating to the Maven 3 build step and want to avoid the accidental creation of projects with this type, you should disable the Hudson:: Maven(legacy) :: Plugin. Read more about managing your plugins in [chapter-plugin-management].

Both the Maven 2/3 project type as well as the Maven 2 build step are part of Hudson as legacy components and are not the focus of active development and improvements. If your existing jobs use either of these we recommend migrating to Maven 3 build step based free-style projects.

In order to be able to keep existing legacy build around without cluttering to user interface or have inexperienced users create builds with the legacy systems, you can enable the blacklist plugin to disable certain views within Hudson without completely disabling the still required plugins.

After configuring the general project options as documented in [chapter-build-creation], you can configure one or more build steps. To add a build step, click on the Add build step button as shown in [fig-maven-3-build-step-default]. To configure a Maven build, select Invoke Maven 3.

The basic and advanced options for configuring a Maven 3 build steps are shown in [fig-maven-3-build-step-default] and [fig-maven-3-build-step-advanced] . When adding a new Maven 3 build step all parameters are pre-populated with the default parameters defined for Maven 3 build steps. These are configured in the global Hudson configuration documented in [chapter-configuration] in [section-configure-maven-3-builder-defaults].

If for some reason you are still using Maven 2 and cannot upgrade to Maven 3 and therefore take advantage of the advanced performance and features of Maven 3 and the Maven 3 integration of Hudson offers you, you should use the Maven 2 (Legacy) integration in a free-style project build step. After configuring the general project options (see [chapter-build-creation]), you can configure one or more build steps. To add a build step, click on the Add build step button as shown in [fig-build-step-maven-2-legacy-default]. To configure a Maven build, select Invoke Maven 2 (Legacy).

The basic and advanced options for invoking a Maven 2 (Legacy) target are shown in [fig-build-step-maven-2-legacy-advanced].

The standard way of invoking a Maven build is to run the clean and install life cycle phases in a command-line call like mvn clean install. This can be easily achieved by adding a Maven build step and adding clean install as a Goals parameter. If so desired these two life cycle phases can also be invoked separately by creating two Maven build steps with separate clean and install parameters. This would cause two separate invocations of Maven in sequence equivalent to mvn clean; mvn install Breaking up the invocations allows you to add further build steps in between and build an arbitrarily complex sequence of Maven and other invocations with completely separate parameters and so on.

You could for example slip a plugin goal invocation in between the clean and install invocations, that prepares the execution environment for your build for example by setting up a test environment like an emulator or a specific database and content. Since you can do this in a separate build step you can invoke a shell script or an Ant target for such tasks, in case it is not automated via a Maven plugin or configuration.

The general configuration for Apache Ant installs on Hudson is available in [section-configure-ant]. You can read about influencing factors for your Apache Maven install, that apply to your strategy for installing Ant as well in [section-installing-maven].

A common scenario for Apache Ant installs is the requirement of a build to have access to Ant tasks as provided in Ant-Contrib like For or If or to have some required libraries like JSch for secure copying with scp available on the Ant class-path. Custom developed Ant tasks can be needed in a similar fashion. A convenient way to achieve this, is the creation of a custom archive containing the Ant install as well as additional libraries necessary. This archive can then be used with the Extract from *.zip/*.tar.gz option to get a fully working Ant and dependencies installed on all build cluster nodes.

After configuring the general project options as documented in [chapter-build-creation], you can configure one or more build steps. To add a build step, click on the Add build step button and select Invoke Ant.

The basic and advanced options for invoking Ant are shown in [fig-configure-ant-build-step].

The Subversion Plugin for Hudson and therefore support for the popular Subversion SCM system is part of the default install of Hudson. It is therefore not necessary to perform any further plugin installation to use Subversion for your project.

Git is the most successful, modern distributed version control system and has gained wide acceptance in the open source community and beyond. and repository hosting services available from multiple suppliers for commercial and open source usage.

The Hudson Git Plugin and therefore support for Git is available in default Hudson installs from version 2.1 onwards. If it is not installed in your Hudson instance, simply find the plugin in the Source Code Management section of the available plugins and install it like any other plugins as documented in [chapter-plugin-management].