Setting up Hudson on port 80 on a Debian or Ubuntu machine

To my delight I discovered there is a debian package of Hudson nowdays.  Installing it was pretty straightfoward, but I wanted to configure hudson to be visible on my server at myserver/hudson, instead of myserver:8080, for a project I'm in.  That turned out to be quite a bit more complicated, but I got it done in the end and documented the process here for others and my own future reference.

My server is running Ubuntu 8.4 Hardy, but the instructions are relatively generic.

Installing Hudson deb package

The Hudson package is not in the default repositories, but that wouldn't be too useful anyway as it would be hard to keep up with the frequent Hudson releases.

Installation instructions for installing the deb package, or see the wiki page for more discussion.

By default the hudson deb package will install hudson in /var/lib/hudson, which also contains a config.xml with some options.  Command line options can be found in /etc/default/hudson.  The hudson log is in /var/log/hudson/hudson.log.  You may want to run

    tail -f /var/log/hudson/hudson.log

while debugging the installation.

You can start Hudson with:

    sudo /etc/init.d/hudson start

Hudson should now be running on port 8080 of your machine.

Remember to register a user and set up access control if you are running the machine on the public internet.

If needed, you can stop Hudson with:

    sudo /etc/init.d/hudson stop

Hudson on port 80

To set up Hudson to run on port 80 (the normal http port) instead of 8080 you could edit /etc/default/hudson and add --httpPort=80 to HUDSON_ARGS.  However, running a service on any port below 1024 requires the service to be run as root on Linux, which is not such a good idea for a compex Java application.  If you try to start hudson with the --httpPort=80 argument in /etc/default/hudson, you'll get a " Permission denied" exception in the log. 

It appears the standard procedure is to run apache (or another webserver), and configure it to hand over processing of a certain path to Hudson.  Mod_proxy seems to be the way to go.

Hudson Prefix

We want to see hudson running on servername/hudson/.  The first step is to change the prefix hudson uses, so we get from servername:8080/ to servername:8080/hudson/.  To do that, add

to the HUDSON_ARGS string in /etc/default/hudson and restart Hudson with e.g.:

    sudo /etc/init.d/hudson force-reload


If you don't have apache installed, use

    sudo apt-get install apache2

to install it.


In many distributions it should be included by default with apache, but you may need to install the mod_proxy module separately:

    sudo apt-get install libapache2-mod-proxy-html

In any case you need to enable it with:

    sudo a2enmod proxy
    sudo a2enmod proxy_http  

By default it is configured to deny all proxying, so edit /etc/apache2/mods enabled/proxy.conf to allow proxying:

    ProxyRequests Off
    <Proxy *>
        Order deny,allow
        Allow from all

[Note that messing up proxy configuration could leave your server as an open proxy, so proceed at your own risk.  I'm just copy pasting code from documentation without fully understanding it...]

In your /etc/apache2/sites-enabled/ directory there should be some file like 000-default or similar, with settings for the site.  Add proxy configurations in it for mapping the /hudson path on the website to localhost:8080/hudson:

    ProxyPass /hudson

You can of course use some other path than /hudson too, in that case remember to also use it with the Hudson --prefix parameter above.

In my case the file looks something like:

    <VirtualHost *> 
        # various stuff ....
        ProxyPass /hudson

You can stop and restart apache to enable the new configuration, or just use:

    /etc/init.d/apache2 force-reload

And you can follow the apache logs for troubleshooting by running

    tail -f /var/log/apache2/error.log

Good luck, and feel free to suggest improvements to this configuration in the comments.