Mercurial Hosting using hg-admin-tools over SSH
++++++++++++++++++++++++++++++++++++++++++++++++++

:Posted: 2008-05-19 23:23
:Tags: Hosting, Mercurial

In this article we'll set up mercurial hosting over SSH. This is very similar to the `Subversion setup <http://jimmyg.org/2007/12/04/subversion-over-svnssh-on-debian/>`_ 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 <http://hg.opensource.lshift.net/hg-admin-tools/file/583ed103e021/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