In a previous post a couple weeks ago, we looked at setting up Mercurial on Windows/IIS 7. Now, I’ll take you through the setup of Mercurial on a RHEL/CentOS server.

Installation

You can use the yum installer to make sure you have Apache 2 installed.

$ yum install httpd
$ httpd -v
Server version: Apache/2.2.3

Same goes for Python. RHEL/CentOS 5 ships with Python 2.4.3 and uses it for many of its system management tools. If your system does not ship with Python, install it first. Mercurial requires at least Python 2.4. Alternatively, you could build and install Python 2.7.1 from source. If you choose to use a later version of Python, you want to make sure you don’t overwrite the existing Python installation unless you know what you’re doing and are familiar enough with the OS to fix it.

I also mentioned in an earlier post that you can’t use Python 3.x due to the fact that Mercurial has not yet made the transition to Python 3 syntax. So keep that in mind as well.

$ python -V
Python 2.4.3

You also need to make sure you have the httpd-devel and python-devel packages installed since we are going to build mod_wsgi and Mercurial from source.

$ yum install httpd-devel
$ yum install python-devel

Let’s now build and install the mod_wsgi Apache module. At the time of writing, the latest version of mod_wsgi is 3.3. Punch in the following:

$ cd ~
$ wget http://modwsgi.googlecode.com/files/mod_wsgi-3.3.tar.gz
$ tar -xvzf mod_wsgi-3.3.tar.gz
$ cd mod_wsgi-3.3
$ ./Configure
$ make
$ su
$ make install

This will install the mod_wsgi.so in /etc/httpd/modules. 

Building the documentation for Mercurial 1.7.3 requires docutils. Before we build and install Mercurial, we need to install docutils. At the time of writing, the latest version of docutils is 0.7. Mercurial requires at least docutils 0.5. Punch in the following to install docutils:

$ cd ~
$ wget http://prdownloads.sourceforge.net/docutils/docutils-0.7.tar.gz?download
$ tar -xvzf docutils-0.7.tar.gz
$ cd docutils-0.7
$ su
$ ./setup.py install

This will install docutils in /usr/lib/python2.4/site-packages/docutils.

Now that we are done installing docutils, we are going to take it a step further and make our own mercurial-1.7.3-0.x86_64.rpm and install from it.

$ cd ~
$ wget http://mercurial.selenic.com/release/mercurial-1.7.3.tar.gz
$ tar zxvf mercurial-1.7.3.tar.gz

Now, edit mercurial.spec in ~/mercurial-1.7.3/contrib/, search for the line containing ‘Version’ and replace ‘snapshot’ with ‘1.7.3’.

$ tar cvf - mercurial-1.7.3 | gzip > mercurial-1.7.3.tar.gz
$ sudo rpmbuild -tb mercurial-1.7.3.tar.gz
$ sudo rpm -ivh /usr/src/redhat/RPMS/x86_64/mercurial-1.7.3-0.x86_64.rpm
$ hg --version
Mercurial Distributed SCM (version 1.7.3)

At this point, you should have successfully installed Mercurial and had Mercurial Python 2.4.3 package in /usr/lib64/python2.4/site-packages/mercurial/.

Configuration

Let’s now configure Apache and mod_wsgi and use the hgweb.wsgi script to serve up Mercurial repositories.

Add the following lines to the httpd.conf in /etc/httpd/conf to have Apache load the wsgi module and map the .wsgi extension for proper handling the next time we start apache:

LoadModule wsgi_module modules/mod_wsgi.so
AddHandler wsgi-script .wsgi

If you installed a different version of Python side by side with Python 2.4.3 that ships with RHEL/CentOS, then you should also make sure WSGIPythonHome is set to your new Python home.

WSGIPythonHome /usr/lib/python2.7

If you skip the above step, mod_wsgi will continue to use Python 2.4.3.

While still in the apache configuration file, make the following changes:

ServerAdmin admin@domain.tld
ServerName domain.tld
DocumentRoot "/var/www/html"
NameVirtualHost *:80 

Now, add two new <VirtualHost> sections to the httpd.conf as follows:

First one is just a one-liner used for requests without a known server name. This should be the first <VirtualHost> deceleration in your httpd.conf. This section will inherit the ‘main’ server configuration.

<VirtualHost *:80></VirtualHost>

The second one will be where we host our Mercurial Server.

<VirtualHost *:80>
   ServerName hg.domain.tld
   ErrorLog /var/log/httpd/hg.domain.tld-error_log
   CustomLog /var/log/httpd/hg.domain.tld-access_log common
   WSGIScriptAlias / /var/www/vhosts/hg.domain.tld/cgi-bin/hgweb.wsgi
</VirtualHost>

By default mod_wsgi runs hgweb.wsgi in what is called embedded mode. Alternatively, you can use mod_wsgi’s daemon mode, to do so add the WSGIDaemonProcess and WSGIProcessGroup directives to the above <VirtualHost> section:

<VirtualHost *:80>
   ServerName hg.domain.tld
   ErrorLog /var/log/httpd/hg.domain.tld-error_log
   CustomLog /var/log/httpd/hg.domain.tld-access_log common
   WSGIScriptAlias / /var/www/vhosts/hg.domain.tld/cgi-bin/hgweb.wsgi
   WSGIDeamonProcess hg.domain.tld user=apache group=apache threads=15 processes=2 display-name=%{GROUP}
   WSGIProcessGroup hg.domain.tld
</VirtualHost>

What this does is creates 15 processes each with 2 threads in a group called hg.domain.tld.

However, if you decide to run mod_wsgi in deamon mode on RHEL/CentOS, you might get the following error.

(13)Permission denied: mod_wsgi (pid=5360): Unable to connect to WSGI daemon process
'hg.domain.tld' on '/etc/httpd/logs/wsgi.5433.0.1.sock' \ after multiple attempts.

This is because child processes cannot access the socket file wsgi.5433.0.1.sock in the runtime directory i.e., logs. 

To fix this, simply add the following line to the httpd.conf, and ideally it should just work.

   WSGISocketPrefix /var/run/wsgi

Next, create two new folders; /var/www/vhosts/hg.domain.tld/cgi-bin where we will host the hgweb.wsgi and the configuration file, and /var/www/vhosts/hg.domain.tld/repos where we will host our Mercurial repositories.

And, copy ~/mercurial-1.7.3/contrib/hgweb.wsgi to /var/www/vhosts/hg.domain.tld/cgi-bin/.

$ cp ~/mercurial-1.7.3/contrib/hgweb.wsgi /var/www/vhosts/hg.domain.tld/cgi-bin/

Now, make the following modification in hgweb.wsgi:

config = "/var/www/vhosts/hg.domain.tld/cgi-bin/hgweb.config"

Create a new file called hgweb.config in /var/www/vhosts/hg.domain.tld/cgi-bin and put the following in it:

[paths]
/ = /var/www/vhosts/hg.domain.tld/repos/**
[web]
allow_push = *
push_ssl = false

Finally, set repository folder permissions as follows and restart Apache:

$ cd /var/www/vhosts/hg.domain.tld/repos/
$ hg init helloworld
$ chgrp -R apache helloworld
$ chmod -R g+rwx helloworld
$ /etc/init.d/httpd restart 

At this point, you should be able to browse any repository you host in /var/www/vhosts/hg.domain.tld/repos via the web interface at http://hg.domain.tld.

Finally, I will finish up by extracting the following paragraph from the blog on how to install and configure Mercurial on Windows/IIS 7. “Unless configured to use authentication, this setup is no more secure than the built-in web server that Mercurial comes packaged with, i.e. hg serve. So, you should also enable the Basic Authentication module for your Mercurial Web Site. Please also note that Basic Authentication is a very simple authentication scheme. You should always use it in conjunction with SSL. Otherwise, your credentials will be sent in clear text over the wire. Once you have SSL configured, also make sure to modify hgweb.config to force SSL on push requests by setting push_ssl to true and/or *preferably and* configure the SSL settings in IIS Apache if you want your site to require SSL.”