Debugging Hgweb

<!> This is a work in progress

How to get hgweb working, the systematic way

1. Why is setting up hgweb so hard?

The short answer is: because setting up web servers is hard. Making a Mercurial server works perfectly generally involves a bunch of tricky independent pieces:

Further, each web server will handle these details differently. Getting any of these wrong will result in a broken setup, which means if you try to get it all working in one go, you'll probably fail.

2. The systematic approach

To deal with the complexity here, we break the problem down into a series of discrete steps that can each be tested independently. At each step, we will be closer to a fully-working configuration and will establish a baseline to compare our future changes against, as well as understanding how all the pieces of the puzzle interact.

At each step:

3. Basics: testing hg serve

The first and simplest test is to get 'hg serve' working. This will ensure you have a minimally working Mercurial install on client and server and a working network connection.

$ hg serve
listening at http://machine:8000/ (bound to *:8000)


4. Push and hg serve

The next step is to enable insecure push support by setting the following option in your Mercurial config and restarting 'hg serve':

; insecure - only for testing!
push_ssl = False
allow_push = *

This test will confirm basic permission issues (though be aware that web servers may change the effective permissions).


5. Web server basics

<!> Even if you're sure this works, do it anyway to double-check your assumptions

Now we should ensure that the basic functionality of the web server is working, meaning basic file serving. Set up your webserver and install a text file in its document root. This will establish that you haven't made any basic errors in your web server install or permissions.


6. Working CGI/WSGI

Depending on whether you're intending to serve with CGI (slow) or WSGI (faster, more complicated), you should now ensure you can serve a trivial CGI or WSGI page. This will test that configuration and file permissions are correct without bringing Mercurial into the picture.

6.1. Unix CGI

Here's a basic test script that will report the running environment

echo "Content-type: text/plain"

6.2. WSGI

def application(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return ["Hello world!\n"]

DebuggingHgweb (last edited 2012-05-08 14:45:37 by mpm)