Setup of Mercurial server with cPanel – the easy way

Posted: March 23rd, 2012 | Author: | Filed under: General | No Comments »

Mercurial is a cross-platform, distributed revision control tool for software developers. In this article will be presented a handy way to install and configure Mercurial on a server with cPanel . All operations presented will only need a standard FTP/SSH access to a user account, except the initial installation of the Mercurial RPM which needs root rights.  This installation procedure is very suitable for those creating websites and wanting a quick solution to track the changes in their source code using a repository stored right next to the website.


The information below were compiled from several sources with some modifications to suit the above needs.  The aim is to use only cPanel and SSH with user rights (e.g. no root required !)  and have a repository ready in 5 minutes.  The repository will then be accessed securely as


Intial preparation:   install the Mercurial package as root

Here is a sample installation from a RPM on an OpenSuse linux:

$ sudo rpm -ihv mercurial-1.0-1.2.x86_64.rpm


Step 1.  Create subdomain

Login in cPanel and create  Do not create the directory under /public_html  so the repository won't mix with the files of the website


Step 2. Create the configuration file of the repository

Use a FTP client and navigate into the directory of the subdomain. Create a folder for your repo, i.e. projectrepo . Use some name other than the one you want to access the repo with because later there will be some URL rewiting rules added into a .htaccess file which won't work otherwise.  In this example the repo url will be made as

Continue navigating into cgi-bin where two files has to be be uploaded: hgweb.config containing the repository configuration and hgwebdir.cgi containing the code needed to run the repository.  Create the two files on your computer and upload them into /cgi-bin:


project = ~/hg/projectrepo


#!/usr/bin/env python
from mercurial import demandimport; demandimport.enable()

import cgitb

import os
os.environ["HGENCODING"] = "UTF-8"

from mercurial.hgweb.hgwebdir_mod import hgwebdir
import mercurial.hgweb.wsgicgi as wsgicgi

application = hgwebdir('hgweb.config')

Change the attributes of hgwebdir.cgi to be executable (0755).  This can be made within the FTP client (at least TotalCommander implements it and probably many other such applications have that option. It is under Files->Change attributes).


Step 3. Initialize repository

Using a SSH console go into the ~/hg folder and run these commands:

hg init

find . -type f -exec chmod 0666 "{}" \;

find . -type d -exec chmod 0777 "{}" \;


The last two commands are needed when the web server (Apache) runs the scripts under a different user than the owner of the account.  In order to create files and folder full write rights are needed for user apache or nobody.

A configuration file will have to be created and uploaded into the new repository. For this , create a file named hgrc with the following content:


description = My repository
push_ssl = false
allow_push = john

# enable snapshot downloads
allow_archive = gz zip bz2

baseurl = /

In this configuration the ssl is disabled which may be a security problem. If your host allows https connections then you may set this to true later. However, the repository is protected through HTTP Basic authentication – see below.

Upload the file above under ~/hg/project/.hg/


 Step 4. Secure the repository

Create a .htaccess file with the following content for uploading in the root of your subdomain:


# Taken from
# Used at
Options +ExecCGI
RewriteEngine On
#write base depending on where the base url lives
RewriteBase /cgi-bin
RewriteRule ^$ hgwebdir.cgi  [L]

# Send requests for files that exist to those files.
RewriteCond %{REQUEST_FILENAME} !-f
# Send requests for directories that exist to those directories.
RewriteCond %{REQUEST_FILENAME} !-d
# Send requests to hgwebdir.cgi, appending the rest of url.
RewriteRule (.*) /cgi-bin/hgwebdir.cgi/$1  [QSA,L]

The rules above allows accessing the repository with an url like instead of and is a replacement for the original procedure described in the Mercurial documentation where one has to modify httpd.conf, as root.

Finally, password protect the repository within cpanel. The operations below will update .htaccess, adding the necessary lines for basic authentication:



Access your repository within a browser with an URL like:

http://john:[email protected]/hg/project

Use the URL above in your Mercurial client too.