#pragma section-numbers 2

= Debugging Hgweb =

<!> This is a work in progress

How to get hgweb working, the systematic way

<<TableOfContents>>

== 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.

== 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

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

== 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

== 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

== 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.

=== Unix CGI ===

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

{{{
#!/bin/sh

echo "Content-type: text/plain"
echo
env
}}}

=== WSGI ===

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

----