This guide assumes you want to set up your own private Mercurial repositories, but want to do so on a server where:

• you have no SSH or shell access, just an FTP connection/file manager 
• it has Python 2.4 or greater already installed
• is a Linux host (although a Windows host should work similarly with this procedure)

Previous guides I’ve come across on the web here and here require you to build Mercurial from source, which might not work depending on how strict your host is at giving you access to programs like the GCC compiler. Our solution here will be to package our own pre-compiled Mercurial binary.

Step 1. Finding out a bit about your host. We’ll need to find out if they run 64-bit processors (there’s a good chance they do), and the version of Python they run. If we don’t know this info, we can assume its 64-bit and Python 2.4, and correct ourselves later.

Step 2. Re-packaging the binary.

Just download the appropriate archive below. For further information on how I arrived at creating these packages, read the rest of this step.

For Python 2.4 | For Python 2.5

These binaries were built from source independently for each version of Python. Inside is already a copy of hgwebdir.cgi, which you will need for the next step.

To compile: For a Debian compilation environment, you’ll need the packages (Python 2.4 for example) python2.4, python2.4-dev, gcc, build-essential, make, in addition to the Mercurial source. You may also need to modify Makefile with PYTHON=python2.4, modify hg with #!/usr/bin/env python2.4 and execute the final install script with Python:
make local
./hg debuginstall

Step 3. Configuring hgwebdir.cgi. The cgi script has to be made aware of the Mercurial files we plan to upload. Open it up in a text editor, and on lines 6, 7, 13, 14, remove the hashes. Also change /path/to/python/lib with your own path. Mine was:

import sys
sys.path.insert(0, “/home/joshjcarrier/python/mercurial“)

import cgitb
cgitb.enable()

Step 4. Uploading the binary and hgwebdir.cgi. Now that we have the binaries, we need to upload them – I put mine at /home/joshjcarrier/python, so the complete path is /home/joshjcarrier/python/mercurial . You’ll also now need to upload the script which will act as the web front-end: hgwebdir.cgi, which can be extracted from Mercurial source or the binaries in step 2. Since my host requires .cgi scripts to be run from cgi-bin, I placed the .cgi in /home/joshjcarrier/public_html/hg/cgi-bin . You’ll also need to change the .cgi’s permissions to 755 – if your FTP client doesn’t support that, see if there’s a web-based file manager that your host provides.

At this point, you should be able to load Mercurial from your web browser. It should be similar to
http://yourwebsiteaddress/hg/cgi-bin/hgwebdir.cgi

If you see the Mercurial repositories page, then success! If you see an error about a missing libpython2.x.so.1.0, then try step 2 again but for a different version of Python.

Step 5. Creating a repository. I suppose you could write a fancy script to help facilitate this, but I’m going to keep this as simple as possible – just upload an existing Mercurial repository, with the root of the repository folder in the same directory as hgwebdir.cgi.

Step 6. UI tweaks and registering a repository listing.

In the same directory as hgwebdir.cgi, you can create a hgweb.config file, and with it you can change the web UI template:

[web]
style = coal
baseurl =
[collections]
/home/joshjcarrier/public_html/hg/cgi-bin/yourhgrepo = your hg repo
 

Other styles nice include “gitweb” and “paper”. Since my /public_html/hg acts as a sub-domain, I have set my baseurl = <blank>. If you haven’t set this up that way, you might specify “hg” or not include it at all.

Step 8. Permissions and URL clean up.

Since I’ve set this up as a HTTP connection, we’ll need to allow push without SSL. In addition, we can provide information to be displayed on the directory listing.

In your hg repo folder, navigate to .hg/ and edit the hgrc file, adding something similar to the following:

[paths]

default = http://yourwebsiteaddress/hg/yourreponame

[web]

contact = Josh Carrier

description = Hello world

push_ssl = false

allow_archive = gz zip bz2

allow_push = joshjcarrier

allowpull = true

allow_read = *

More configuration options are listed at Selenic.

Now for authentication, first password protect your entire repository directory. Most web hosts run cPanel or an equivalent, and our goal will be to use the output for our final step. The users you create here will be Mercurial user accounts. You might consider creating a guest account to be used for read-only access. On password-protecting my /hg directory, a .htaccess file is generated. Open it up and look for the particular line:

AuthUserFile “/home/joshjcarrier/.htpasswds/public_html/hg/passwd“

Now you’re ready to finish authentication. Overwrite the .htaccess file in the /hg directory with something like this.

AuthName "Hg Repository. Read-only=guest/guest"
AuthUserFile “/home/joshjca1/.htpasswds/public_html/hg.joshjcarrier.com/passwd”
AuthType Basic
require valid-user

DirectoryIndex cgi-bin/hgwebdir.cgi
<IfModule mod_rewrite.c>
Options +ExecCGI
RewriteEngine On
RewriteRule ^$ cgi-bin/hgwebdir.cgi  [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule (.*) cgi-bin/hgwebdir.cgi/$1  [QSA,L]
</IfModule>

 

And if all is well, you now have access at http://yourwebsiteaddress/hg/ for the directory listings and you can specify http://yourwebsiteaddress/hg/yourreponame for push/pull.

Tip 1: for some reason, I couldn’t authenticate if my password contained certain special characters, so if you can’t authenticate right away, try dumb-ing down your password complexity… any input on why this is so would be great.

Tip 2: make sure the repository is exactly as listed on the directory. Easiest way is to copy the link URL under the “Name” column. This includes escape characters, like %20.

And the implementation is available at http://hg.joshjcarrier.com (user=guest,pass=guest).