Home Blog CV Projects Patterns Notes Book Colophon Search

Mercurial Hosting using hg-admin-tools over SSH

19 May, 2008

In this article we'll set up mercurial hosting over SSH. This is very similar to the Subversion setup described earlier but we'll also make use of LShift's hg-admin-tools to automate some parts of the set up.

I've got to say I don't really understand the ssh-agent instructions from the README so this is my best stab. If it is wrong please let me know. There are some instructions here http://kb.iu.edu/data/aeww.html

First install mercurial, set up a new user and ensure you have Python 2.5:

apt-get install python2.5 python2.5-dev mercurial
adduser hgadmin

Then give the hgadmin user sudo priviledges with visudo before becoming hgadmin and moving to the home directory:

visudo
su hgadmin
cd

Create a .ssh directory:

mkdir ~/.ssh

You'll also need an updated version of mercurial otherwise an import fails later on:

wget http://www.backports.org/debian/pool/main/m/mercurial/mercurial_0.9.5-2~bpo40+1_amd64.deb
sudo dkpg -i mercurial_0.9.5-2~bpo40+1_amd64.deb

At this point you need to have ssh-agent running and set up. Create a new key pair and copy the public key to the server like this:

james-gardners-macbook-air:~ james$ ssh-keygen -t dsa -f ~/.ssh/id_dsa -C "james@macbook.3aims.com"
Generating public/private dsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/james/.ssh/id_dsa.
Your public key has been saved in /Users/james/.ssh/id_dsa.pub.
The key fingerprint is:
46:1e:48:06:b4:cd:ff:c7:e0:2e:db:77:59:5e:d0:0d james@macbook.3aims.com

james-gardners-macbook-air:~ james$ scp ~/.ssh/id_dsa.pub hgadmin@78.47.146.254:.ssh/authorized_keys
hgadmin@78.47.146.254's password:

james-gardners-macbook-air:~ james$ scp ~/.ssh/id_dsa hgadmin@78.47.146.254:.ssh/
hgadmin@78.47.146.254's password:

Now you should be able to login as hgadmin using the password you set on your private key:

ssh hgadmin@78.47.146.254

Set up ssh-agent (I don't know why we are doing this bit really but the install fails without it:

exec `ssh-agent`
ssh-add

This will add the .ssh/id_dsa key to ssh-agent so that in the next step when we run install, it will be added correctly when the command ssh-add -L is called:

We need to get the hg-admin-tools:

mkdir ~/lib
cd ~/lib
hg clone http://hg.opensource.lshift.net/hg-admin-tools

Make sure there isn't already an hg user then run this:

cd hg-admin-tools
./install

This creates a new user called hg without password signins and runs hginit to setup the hgadmin repository.

Changing Permissions

Now that the software is installed you need to know how to administer it. Back on the machine you signed in from (in my case the Macbook) you can checkout the hgadmin repository:

hg clone http://hg@78.47.146.254/hgadmin

This works because the same key you used for password-less signin to the hgadmin account has been setup by the hginit script to allow you to signin with the same key to the hg user account.

Creating New Repositories

Users authorized to do so (such as yourself) can create new repositories like this:

mkdir new-repository
cd new-repository
hg init
hg clone . ssh://hg@78.47.146.254/my-project-name

You can then do things like this:

hg add *
hg commit -m "Adding initial files"
hg push ssh://hg@78.47.146.254/my-project-name

Then you can check out the changes somewhere else:

hg clone  ssh://hg@78.47.146.254/my-project-name new-copy-of-my-new-project

or update another checkout with the new changes:

hg pull
hg update

Each operation involving the server will prompt you for the password for your private key.

Back to the README

At this point you should be able to follow the README again. Particularly the HG-SSH-ACCESS.CONF section. It explains how you can add keys for new developers to the keys directory and configure permissions by changing the hg-ssh-access.conf. hen you check in changes some hooks are run to update the .ssh/authorized_keys file on the server to work with the new permissions.

Web Interface

Now let's set up a web interface for the hosting. You can use hg serve to provide a web interface to a particular repository. For example to serve the new-project-name repository you would do this:

cd /home/hg/repos/new-project-name
hg serve

This would start a server on http://localhost:8000 to serve the repository. You can also customise the styles. An easier style to use is gitweb:

hg serve --style gitweb

You can create your own styles by copying and modifying an existing template:

sudo cp -r /var/lib/python-support/python2.4/mercurial/templates/gitweb/ /var/lib/python-support/python2.4/mercurial/templates/james
hg serve --style james

There's documentation on how to do this at http://hgbook.red-bean.com/hgbookch11.html

Quick Reference Cards

These are handy too:

http://www.ivy.fr/mercurial/ref/v1.0/Mercurial-QuickStart-v1.0-120dpi.png http://www.ivy.fr/mercurial/ref/v1.0/Mercurial-Usage-v1.0-120dpi.png