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:

• a properly-functioning webserver
• working SSL
• working CGI/WSGI configuration
• working webserver authentication
• working Mercurial install
• proper repository ownership and permissions
• proper config ownership and permissions
• proper hgweb ownership and permissions
• proper config of allowed users

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:

• check the relevant documentation
• go through the test checklist
• back up the working configuration before proceeding to the next 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)

Tests:

• repository history can be browsed with a remote web browser
• remote client can clone the hg serve URL
• above tests continue to work on default HTTP port with '--port 80'

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':

[web]
; 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).

Tests:

• remote browsers still work
• clone still works
• push works for any user

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.

Tests:

• file content is visible as plain text at the expected URL in a remote browser

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"
echo
env

6.2. WSGI

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