Publishing your mercurial-server repositories to the Web

By: on March 5, 2010

I got a couple of queries recently on how to make your mercurial-server repositories publically readable over HTTP. Happily this isn’t hard to do, and doesn’t really touch on mercurial-server itself. Here’s how we do it on our Debian systems; in what follows I assume that you have installed mercurial-server on, and that you’re not already using that machine as a web server for anything else. First install these packages; note that they tend to have a lot of stuff you don’t need marked as recommended, so don’t install those things:

apt-get --no-install-recommends install apache2 libapache2-mod-fcgid python-flup

Create the following four files:


/var/lib/mercurial-server/repos = /var/lib/mercurial-server/repos


style = gitweb
allow_archive = bz2 gz zip
baseurl =
maxchanges = 200


#!/usr/bin/env python

from mercurial import demandimport; demandimport.enable()

import os
os.environ["HGENCODING"] = "UTF-8"
os.environ["HGRCPATH"] = "/etc/mercurial-server/hgweb.hgrc"

from mercurial.hgweb.hgwebdir_mod import hgwebdir
from mercurial.hgweb.request import wsgiapplication
from flup.server.fcgi import WSGIServer

def make_web_app():
    return hgwebdir("/etc/mercurial-server/hgweb.config")



<VirtualHost *>
    AddHandler fcgid-script .fcgi
    ScriptAlias / /etc/mercurial-server/hgwebdir.fcgi/
    ErrorLog /var/log/apache2/hg/error.log
    LogLevel warn
    CustomLog /var/log/apache2/hg/access.log combined

Finally run these commands as root:

chmod +x /etc/mercurial-server/hgwebdir.fcgi
mkdir -p /var/log/apache2/hg
cd /etc/apache2/sites-enabled
rm 000-default
ln -s ../sites-available/hg
/etc/init.d/apache2 reload

Your files should now be served at . Sadly because of a design flaw in hgwebdir, there’s no easy way to get Apache to handle the static files it needs, but these are pretty small so there’s no harm in letting hgwebdir handle them. The “rm 000-default” thing seems pretty undesirable, but without it I can’t seem to get this recipe to work.

I’ve chosen FastCGI as the connector. This has the advantage that

  • unlike CGI, it doesn’t fork a new handler on every request
  • unlike mod_python, it keeps your Mercurial handler separate from your web server
  • unlike SCGI, it will automatically start the service for you if it’s not already running, which is a massive convenience

I’m not aware of any other way of working that offers all three advantages.

As soon as a version of lighttpd with this bug fixed makes it into Debian, I’ll add my recipe for that.



  1. ekke says:

    hi paul,
    thanx for posting this here.
    …think it should work – can reach the server

    also tested to serve single repositories using hg serve from terminal. then I get the repository from apache http://:8000

    but if I try to reach http:// then the browser says:
    The requested URL / was not found on this server.
    Apache/2.2.14 (Ubuntu) Server at Port 80



  2. ekke says:

    sorry – there was html code inside – I meant:

    http://myserver:8000 (works fro single hg serve)
    http://myserver (got the error)

  3. ekke says:

    tested more:
    found out: libapache2-mod-fcgid wasn’t installed
    after installing I got an Error 500
    “UTF-8″ should be “UTF-8”
    “/etc/mercurial-server/hgweb.hgrc” should be

    ”/etc/mercurial-server/hgweb.config” should be

    now I’m getting a website with a Repositories List 🙂



  4. Manilal says:

    Hello Paul,
    First of all apologies for being off-topic.

    I have a small team of developers working on a couple of projects. We are seriously considering mercurial for our source control and we own a shared hosting account. The shared hosting account provides us a SSH account and mercurial is already installed.

    I would like to know whether mercurial-server can be installed on a shared hosting(with only one SSH account). If yes, do you have any instructions on how to do this.

    This would be a great help for developers like me who can’t afford an expensive dedicated server.


  5. Paul Crowley says:

    Manilal: It can, but it’s not ideal. First, it will be hard to use the account for anything else because the authorized_keys file will be repeatedly rewritten; secondly, there’s nothing to automate the install, you’ll have to understand how mercurial-server works and craft your own .mercurial-server file by hand to get the whole thing running.

    If you can sort out a dedicated SSH account for it, that would be better. Even better would be an account with a provider like Bytemark, who will give you root access on a virtual Unix machine for £15/month.

  6. Manilal says:

    Thanks for your quick and prompt reply. I now understand the issues behind it. Bytemark looks good, but I have already paid for the hosting. So it would be great loss for me if I move quickly. Anyways, thank you very much for the clarification and recommendation.


  7. Andrew says:

    I tried to follow these directions on my VPS running Karmic. I’m getting an 500 internal server error.

    Checking the error log (/var/log/apache2/hg/error.log) reveals “Premature end of script headers: hgwebdirfcgi” and “(104)Connection reset by peer: mod_fcgid: error reading data from FastCGI server”

    Any thoughts on how I might troubleshoot this? Thanks.

  8. Andrew says:

    Ok, I fixed my problem. Apparently, copying and pasting from your example hgwebdir.fcgi resulted in inconsistent quotation marks. I replaced all quotation marks and reloaded apache and that did the trick.

  9. Me says:

    Do yourself a big favor and change the blue on light blue theme (what were you thinking ). Had to leave without reading a word.

  10. Me says:

    And change the grey on white while youre at it.

  11. tonyg says:

    @Me, you might not be aware of your browser’s View menu’s Page Style -> No Style option, which will present not only this, but any website in a simple black-on-white style. By making full use of the tools you have available to you, you can exercise quite a significant measure of control even over those portions of the web curated by others. Other useful tools for customising the ways websites are presented to you include Stylish, Greasemonkey and Firebug.

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>