I once wrote that Nginx was my project management software. While not entirely true, I am very fond of Nginx for a variety of tasks, one of which is fronting Hudson. As I recounted in my previous post, getting this right will save you a megagigaton of grief.

This technique works with almost all modern unixes.  It probably works just fine in Mac OS X.  It probably doesn't work for you windows folks.  For this example, I used the very latest and greatest Ubuntu.

Preliminaries: Nginx and Hudson.


aptitude install hudson

That ought to be it for installation. Now comes the tricky part: I want to install Hudson at its usual place, port 8080. But I want it to be fronted by Nginx so I can use Nginx's basic auth mechanism (really, I'm not doing rocket science here).

First, change where hudson will run. On Ubuntu, that means editing /etc/default/hudson and changing the last line to read:

HUDSON_ARGS="--webroot=/var/run/hudson/war --httpPort=10080 --httpListenAddress=localhost"

There. We've now moved Hudson to port 10080, and told it only to listen to the local IP address.  Don't use "" instead of "localhost"; it doesn't work.


aptitude install nginx

Next, set up Nginx to listen on port 8080 and proxy to 10080. Ubuntu actually does something very nice with the Nginx configuration, something apache-like. It lets you set up independent server configuration files in the directory /etc/nginx/sites-available, and then activates them by linking to them in /etc/nginx/sites-enabled, the contents of which are made part of the Nginx configuration by a wildcard include directive in nginx.conf. This made it easy. First, edit the file /etc/nginx/sites-available/hudson and put this in:

upstream hudson {

server {
        listen          8080;
        server_name     your.server.name.com;
        root            /var/lib/hudson;

        access_log      /var/log/nginx/hudson_access.log;
        error_log       /var/log/nginx/hudson_error.log;

        location / {
                proxy_set_header  X-Real-IP  $remote_addr;
                proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header Host $http_host;
                proxy_redirect off;
                proxy_pass http://hudson/;

                auth_basic "Hudson integration server";
                auth_basic_user_file /var/opt/hudson/htpasswd;

Change "your.server.name.com" to whatever address you're fronting.  Now change to /etc/nginx/sites-enabled and link the two together:

ln -s ../sites-available/hudson .

Note the ending period, meaning "link it here."

If you're not running Ubuntu, the Nginx configuration file is still relatively easy to live and work with.  You can still make your hudson proxy configuration an independent file, named "hudson.conf" for example purposes, in the nginx configuration directory, then add this to the http directive section of nginx.conf:

include /etc/nginx/hudson.conf

In the last two lines of our configuration file I specified an auth_basic password file; we have to create it next to make Hudson work correctly:

mkdir -p /var/opt/hudson
cd /var/opt/hudson
htpasswd -b -c htpasswd user1 password1
htpasswd -b htpasswd user2 password2

... etc., etc.  The first htpasswd command includes the "-c" option, which will create a new htpasswd file.  If you already have one, don't use it.  If you don't have one, don't use it more than once because it will destroy any existing htpasswd files you have present.  The "-b" means "take the password from the command line."  If you would rather do it in a way that people reading over your shoulder can't see it, and that won't get recorded in your .bash_history file, drop the "-b" argument.

Depending upon your set-up, you may have to go back along that path and ensure that all directories are readable by the Nginx user, www-data.

Now you start everything:

/etc/init.d/hudson start
/etc/init.d/nginx start

Provided you've done it correctly, you should now be able to browse to port 8080 and see your Hudson running in all its glory-- after typing in your username and password.


If it didn't work, you can first ensure that Hudson is running by visiting the box on which you installed it and using Lynx to get to it:

lynx http://localhost:10080/

And you ought to be able to visit Hudson on the console.  That should help you track down if the problem is with Hudson, or Nginx, or your firewall.