Setup Mercurial on Debian 5 with Apache

Mercurial Version Control

Mercurial has become more and more popular to developers. It has lots of advantages compared with Subversion. For more information, please read this excellent tutorial:

I was asked to set up Mercurial for my clients the other day, and there isn’t much resource out there to follow. It took me one whole day to get this done. I think it is worth to share my experience here, and hopefully it will help others some day. Please let me know you have been here.

OS Selection

After researching, I found Debian has the best support for Mercurial in all Linux Platforms. I have been too familiar with Centos, Fedora and I always wanna play a little bit with Debian. Some one told me long long ago that Debian is the most stable Linux System… So I figured, well, let us go with Debian.

Install Mercurial

Debian has Mercurial package for install, but the version is quit old (1.0 or something). No worries, Debian has this great thing called: Backports where you can try lots of newer version software. Follow the Backports Instruction you can easily set up your Debian system getting packages from Backports. Now, let us install Mercurial:

apt-get -t lenny-backports install "mercurial"

You are done. Test it by running:

hg version

You should see:

Mercurial Distributed SCM (version 1.3.1)

Copyright (C) 2005-2009 Matt Mackall <> and others
This is free software; see the source for copying conditions. There is NO

You can also try with creating a new repository:

hg init test

It will create a repository called “test” in your current folder.

Mercurial Repositories Publishing

Now we have Mercurial Central Server running, but how do you share to others. This is where Publishing comes from.
You may want to read this article to know more about Mercurial Publishing. There are many ways to publish your Mercurial Repository. I decided to go with the most popular one – Apache Web Server.

Install Apache mod_wsgi

If goes with Apache, it is recommended to use Apache mod_wsgi to talk to Mercurial. Here is the how-to instruction.

mod_wsgi doesn’t come with Apache by default. Now we need Backports’ help again.

Install Apache 2 if you haven’t done so:

apt-get install apache2

Install mod_wsgi

apt-get install libapache2-mod-wsgi

Restart Apache 2, you will find you have mod_wsgi already loaded.

Download hgwebdir.wsgi

hgwebdir.wsgi is needed for Apache to talk to Mercurial. It is in Mercurial Source package. We need to download it separately. Make sure you download the same version one. Here I just run:

tar -zxvf mercurial_1.3.1.orig.tar.gz

The hgwebdir.wsgi should be sitting in the contrib folder.

Apache Configuration

First of all, make two folders:


Now put hgwebdir.wsgi into /var/www/vhosts/

New a file called hgweb.config in /var/www/vhosts/

style = coal
allow_push = *
push_ssl = false
/ = /var/www/vhosts/**

That’s just for hgwebdir.wsgi to read HG configurations. You should change the setting in this .config file.

Update: In hgwebdir.wsgi there is a line that lists the path to hgweb.config. This line *must* be an absolute path!! even when the files are in the same directory. (Thanks to hg)

Time to change Apache custom config file: /etc/apache2/httpd.conf :

<VirtualHost *:80>
 DocumentRoot /var/www/vhosts/
 ErrorLog /var/log/apache2/
 CustomLog /var/log/apache2/ common
 WSGIScriptAliasMatch ^(.*)$ /var/www/vhosts/$1
 # To enable "daemon" mode, uncomment following lines. (Read mod_wsgi docs for more info)
 # WSGIDaemonProcess user=USER group=GROUP threads=15 maximum-requests=1000
 # some more interesting options (tested on mod_wsgi 2.0):
 # processes=2 umask=0007 inactivity-timeout=300
 # WSGIProcessGroup
 <Directory /var/www/vhosts/>
 Options FollowSymlinks
 DirectoryIndex index.html
 AllowOverride None
 Order allow,deny
 Allow from all
 <Directory /var/www/vhosts/>
 Options ExecCGI FollowSymlinks
 AddHandler wsgi-script .wsgi
 AllowOverride None
 Order allow,deny
 Allow from all

Don’t panic, you are almost there.

Create Mercurial Repository

Now we can officially create a repository. You should always create in


for Apache2 to locate it. You will also need to change your repository folder permission to allow Apache 2 to write it.

cd /var/www/vhosts/
hg init firstrepos
chown www-data.root firstrepos/ -R

Now, restart Apache

/etc/init.d/apache2 restart

Try browse:

You should see something like:

Eclipse Mercurial

You already get your job done. This part is optional. I am Eclipse fun ~

Follow instruction on this website to set up your Eclipse with Mercurial.

Please note: Sometimes Eclipse Mercurial complains can’t find hp.exe, well, you need to manually guide it.

Trouble shooting:

1, Firewall – Did you open at least Port 80

2, Add below to your Apache 2 configuration file to avoid Apache warnings


3,The Apache Log file path could be different on your system.



English is not my first language, please forgive any errors above. Hopefully you will find it useful.

6 thoughts on “Setup Mercurial on Debian 5 with Apache”

  1. thanks for the info. one thing that should be updated, in hgwebdir.wsgi there is a line that lists the path to hgweb.config. This line *must* be an absolute path!! even when the files are in the same directory.

  2. I did everything + the comment of hg and still cannot access mercurial via

    Also checked that the troubleshoot issues are OK.

    If it helps when I visit I can see

    Mercurial Repositories
    Name Description Contact Last change

    plus the logo of mercurial… No content though!

    Could you please provide any further help

  3. @ross Thank you for the great introduction, it helped me get things up and running quickly.

    @krap To get it working I set the path to hgweb.config file in the hgweb.wsgi file, hope that helps.

    Happy new year everyone 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *