Chapter 2. 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.

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

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

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

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

Figure 2.1. Hudson Application Window

figs/web/home-job-list.png

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.

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

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

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

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

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

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

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

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

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

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

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

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

2.7. 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 Figure 3.2, “Configuring 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 6.2.1, “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.

2.8. Backing up Hudson Data

A full backup would be the complete content of your Hudson home directory as explained in Section 2.7, “Hudson Related Files and 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.

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

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