But first, why do I want to switch from SVN to Mercurial? Basically the most appealing argument for me was the fact, that with Mercurial I am able to work offline with my repository. Besides that, I always had issues with the way SVN was handling tags and branches. Especially merging changes from a branch back into the trunk was always a pain. I did not need to use that functionality often but when I did, I always ended up doing it twice, because I could not remember which way to do it right.

So, in this article I will describe my setup of Mercurial served via FastCGI behind the nginx webserver. The approach is similar to the integration of PHP into nginx. You need the spawn-fcgi tool from the lighttpd distribution. The following steps should work on a recent Debian or Ubuntu distribution.

The first step is to install Mercurial and some necessary libraries to create the fcgi-wrapper for Mercurial:

aptitude install mercurial python-flup

Now you can already start defining your Mercurial repositories. Here are some steps to create a small example repository:

cd /tmp
hg init hgtest
cd hgtest
echo "Hello world." > readme.txt
hg add readme.txt
hg commit -m "Initial commit"

You now have a Mercurial repository with a single file. The command hg log should show you a single changeset with our commit comment.

Now, let’s start configuring nginx to integrate Mercurial. We will use FastCGI talk connect Mercurial to nginx. User authentication will be done via nginx. It is a good idea to use HTTPS for communication with Mercurial, but we will focus on a standard HTTP setup.

Let’s setup a virtual host for Mercurial. Open /etc/nginx/sites-available/your_domain_name and add the following server definition:

server {
        listen 80;
        server_name YOUR_MERCURIAL_DOMAIN;
 
        location / {
                auth_basic "Secure Login";
                auth_basic_user_file /tmp/mercurial_users;
                fastcgi_pass 127.0.0.1:9001;
                fastcgi_param SCRIPT_FILENAME /tmp$fastcgi_script_name;
                fastcgi_param PATH_INFO $uri;
                fastcgi_param REMOTE_USER $remote_user;
                include fastcgi_params;
        }       
}

The above settings will setup a new virtual host, where all traffic is redirected to the Mercurial FastCGI wrapper. It is important that you forward the PATH_INFO and REMOTE_USER variables. Mercurial will not work correctly without these.

Now reload the nginx configuration:

/etc/init.d/nginx reload

And create the password file:

htpasswd -c /tmp/mercurial_users MYLOGIN

Mercurial uses a central configuration file. In this file we can specify locations for our mercurial repositories. The following file will enable all mercurial repositories found in the /tmp directory. It also changes the theme to gitweb which is a bit clearer than the default theme. Create the file /tmp/hgweb.config with the following contents:

[collections]
/tmp = /tmp
 
[web]
style = gitweb
baseurl =

Mercurial uses a second configuration file for each repository where you may specify details about the repository and security settings like who may push changes into the repository. The configuration should be placed into the file /tmp/hgtest/.hg/hgrc and could look like this:

[web]
contact = YOUR NAME
description = DESCRIPTION OF PROJECT
style = gitweb
push_ssl = false
allow_archive = bz2 gz zip
allow_push = LOGIN_NAME

Now we need to grab the following script from the Mercurial repository and place it into the /tmp directory: http://selenic.com/repo/hg/raw-file/tip/contrib/hgwebdir.fcgi. Now edit this file and replace the line WSGIServer(hgwebdir('hgweb.config')).run() with WSGIServer(hgwebdir('/tmp/hgweb.config')).run().

The last step is to set the correct filesystem rights for your repository:

chown -R www-data.www-data /tmp/hgtest

That’s it. Now we can start the FastCGI process via:

spawn-fcgi -a 127.0.0.1 -p 9001 -u www-data -g www-data -f /tmp/hgwebdir.fcgi -P /var/run/fastcgi-mercurial.pid -C 1

It makes sense to write the above line into /etc/rc.local so that it will start up automatically when you reboot the server.

Further information about configuring your Mercurial server can be found in the Mercurial Wiki.

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
 
RewriteCond %{REQUEST_URI} !(\.gif)|(\.jpg)|(\.png)|(\.css)|(\.js)|(\.php)$
 
RewriteCond %{REQUEST_URI} ^(.*)$
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule .* sapphire/main.php?url=%1&%{QUERY_STRING} [L]
</IfModule>

So every file which does not end in .gif, .jpg, .png, .css, .js and .php and where the file does not exist will be rewritten.

I chose a somehow stripped down version of these rules which looks in Nginx notation like this:

if (!-f $request_filename) {
    rewrite ^/(.*?)(\?|$)(.*)$ /sapphire/main.php?url=$1&$3 last;
}

If a requested file is not found, the rewriting engine will parse the request string for all elements before a ‘?’. This substring will be pasted as the url parameter to main.php. Everything after ‘?’ will be added as additional parameters. This rewrite rule seems to be working and I haven’t encountered any problems so far.

The idea behind this setup is that nginx will listen on port 80 for incoming connections, identify whether the client requests a static file or a dynamic webpage. In case of a static file it will deliver the file itself. In case of a dynamic request it will forward that request to the Apache server.

So let’s get started. First we need to download and unzip the lates stabel version of nginx. Currently this is verions 0.6.32. Compilation and installation is a done with the usual steps:

./configure
make
make install

This will install nginx in the directory /usr/local/nginx. I usually like to have all my configuration files under /etc, so let’s copy the configuration folder over:

cp -r /usr/local/nginx/conf /etc/nginx

The sample configuration file nginx.conf is well suited as a starting point. I would recommend to uncomment / change the following settings in the main section:

user www-data www-data;
worker_processes 2;
pid /var/run/nginx.pid;

In the http-section you could alter the following settings:

tcp_noauth on;
gzip on;

The English nginx wiki contains a very good documentation on these settings.

Nginx has full support for name based virtual hosts and you need to create a server-section in the config for every virtual host that is configured in Apache. But first create a new configuration file /etc/nginx/proxy.conf which contains the basic proxy settings as found in the nginx wiki:

proxy_redirect          off;
proxy_set_header        Host            $host;
proxy_set_header        X-Real-IP       $remote_addr;
proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
client_max_body_size    10m;
client_body_buffer_size 128k;
proxy_connect_timeout   90;
proxy_send_timeout      90;
proxy_read_timeout      90;
proxy_buffers           32 4k;

These settings will be reused in every virtual host. The default virtual host is used as fallback in case no specific configuration for that virtual host can be found. To configure this default host, replace the server-section in the file /etc/nginx.conf with the following block:

server {
    listen       XXX.XXX.XXX.XXX:80 default;
    server_name  _;
    access_log /var/log/nginx/default.access.log main;
 
    location / {
        proxy_pass http://127.0.0.1:80;
        include /etc/nginx/proxy.conf;
   }
}

Replace XXX.XXX.XXX.XXX with the extern IP address of the server. The above configuration is a pure proxy configuration which will pass all the traffic to the Apache server that is listening on 127.0.0.1:80.

To be flexible in the virtual host configuration, I like to maintain one configuration file per virtual host in a separate directory. We can include all configuration files from a certain directory into the nginx configuration by adding the following line after the server-section:

include /etc/nginx/sites-enabled/*;

So every time you want to setup a new virtual host, you just need to add a new configuration file to the directory /etc/nginx/sites-enabled. Here is a template for that file:

server {
    listen XXX.XXX.XXX.XXX:80;
    server_name foobar.com www.foobar.com;
 
    location / {
        proxy_pass http://127.0.0.1:80;
        include /etc/nginx/proxy.conf;
    }
 
    location ~* ^.+.(jpe?g|gif|png|ico|css|zip|tgz|gz|rar|bz2|doc|xls|exe|pdf|ppt|txt|tar|mid|midi|wav|bmp|rtf|js|swf|avi|mp3)$ {
        expires 30d;
        root /var/www/foobar.com/htdocs;
    }
}

This configuration will setup the virtual host foobar.com. You can define all alias addresses with the configuration directive server_name. All requests that match one of the above file extensions will be delivered directly by nginx from the directory /var/www/foobar.com/htdocs. All other requests are forwarded to the Apache server.

Before nginx can be started we need to make sure that Apache only listens on the address 127.0.0.1 for requests and not on the external IP address. In Debian this is done in /etc/apache2/ports.conf. Change this file to:

Listen 127.0.0.1:80

Also make sure, that the VirtualHost directives in the Apache configuration files do not include an IP address. They should look like this:

<VirtualHost *:80>
    ServerName foobar.com
...
</VirtualHost>

The directive NameVirtualHost should look like this (also without an IP address):

NameVirtualHost *:80

Now you can restart Apache:

/etc/init.d/apache2 restart

And start nginx:

/usr/local/nginx/sbin/nginx -c /etc/nginx/nginx.conf

You can reload the nginx configuration without stopping nginx:

kill -HUP `cat /var/run/nginx.pid`

On my server some quick benchmarks have shown that nginx can deliver static content up to 10 times faster than Apache. The amazing thing is that not only did it deliver the content faster, there was nearly no impact on CPU or memory. With combining Apache and nginx we can have the best of both worlds, nginx for static files and Apache for dynamic content.