step-by-step install Mercurial Server on Ubuntu

This is an add-on to part 1 of my DVCS – blogseries – I want to describe my way how to install a remote Mercurial Server using ssh on Ubuntu. Because we’re using Mercurial and also ssh, you should read my other blog entries about installing Mercurial and ssh. On the client site we also need ssh, Mercurial and HgEclipse installed (see also part 1)

updated 2010-03-12: hgeclipse now allows you to create and init remote ssh repositories

If you’re developing Open Source software, then you can use Bitbucket or Sourceforge to host your remote Mercurial repositories. (see part 4) – you can also use Bitbucket for private Repositories.

But sometimes there’s the need to host a Mercurial repository on your own server. If all users are working in a LAN, then you can easy work with Local Repositories as blogged here. If you really need a secure Server for remote clients, then this blog will help you.

Prerequisites: Mercurial and HgEclipse installed at Client, Mercurial installed at remote Ubuntu, ssh installed at Client and Server, ssh keys already generated.

Install Mercurial-Server

There are some ways to run a remote Mercurial Server – I’m using mercurial-server from LShift. You can download .deb Packages from here or – much easier – let Ubuntu do the work.

Open System -> Administration -> Software Sources:

add to “Other Software”

deb http://de.archive.ubuntu.com/ubuntu lucid main universe

you should use a mirror from your region – please replace “de.archive.ubuntu.com” – this page lists all download sites.

After “Reload” Ubuntu knows “mercurial-eclipse” and you can install as usual:

sudo apt-get install mercurial-server

Hint: Be sure that your public key is installed on Ubuntu and ssh-agent is running and also knows your key (if not: ssh-add is the magic command – all described here)

We’re nearly finished on the server – one step is left: mercurial-server has to know your user as root. At

/etc/mercurial-server/keys

you’ll find the public keys of root users and normal users. After installing mercurial-server no keys are there.

Open your terminal, then we’ll copy your public key into /etc/mercurial-server/keys/root:

ssh-add -L > my-key
sudo cp my-key /etc/mercurial-server/keys/root/yourUserName

mercurial-server uses a special user named “hg” which is the only one having access to your remote repositories. We have to refresh the authentication:

sudo -u hg /usr/share/mercurial-server/refresh-auth

Thats all at the server side.

Behind the scenes

You should carefully read about “Sharing Mercurial repositories with mercurial-server” to understand how it works and to know all ways to configure access of users to repositories.

This documentation of mercurial-server describes all using the commandline, where my blog series focus is on “How to use DVCS like Mercurial without commandline, but from Eclipse”

Some things you should know:

• “hg” is a special user to access repositories using ssh like “ssh://hg@<server>/<yourProject>”
• there’s no normal access to user “hg” – all is controlled by mercurial-server
• all remote users are authenticated by their public key
• remote users can be “root” or “normal” users
• there’s a special repository hgadmin – you can use this to do all configurations remote

Clients of mercurial-server

If you try to login as user “hg” it’s not possible:

You can only use “hg” to access repositories using ssh key authentication.

manage hgadmin from Eclipse

“hgadmin” is a special repository to manage user access to repositories. Only root users with public key on the server are allowed to access hgadmin repository – that’s why we added our public key to /etc/mercurial-server/keys/root/<username> on the server.

It’s recommended to use an extra workspace only to manage “hgadmin”.  Create this workspace and then “Import -> Mercurial -> Clone existing Mercurial Repository“:

We want to clone from “ssh://hg@<yourServer>/hgadmin“:

Now select the one and only “hgadmin” project:

It’s a good idea to change the default visibility Filters to see all files:

please uncheck “.* resources” to view all files:

You’ll see an empty Project – that’s ok:

Now it’s up to you to add all users – here’s an example adding the public key of user “johnny depp“:

You can add as many users as you want.

You can also add root users if there are others with the right to administrate “hgadmin”:

hgadmin/keys/root/<name>/id_rsa.pub

If you have normal users with restricted access, you can also define

hgadmin/keys/<name>/id_rsa.pub

where the acces rules are under

hgadmin/access.conf

please read the mercurial-server documentation.

Now add and commit the changes to our cloned repository:

If you’re done – “push” it to the remote server:

verify the changesets:

Click “Finish” and you’re done 🙂

Init and push / pull to the remote server

Now let’s see how we can initialize and push repositories to the remote server. Switch to a workspace where you already have a repository you want to push into a new repository on the remote ssh server.

Unfortunately (at the moment) it’s not possible to use HgEclipse to initialize a Repository on a remote ssh server, (Issue 11024) so this is the only one command we have to execute from the commandline:

hg init ssh://hg@<yourServer>/<yourRepositoryName>

Thanks for fixing Issue 11024 . Now you can create and init remote Repositories from HgEclipse inside the IDE:

This initializes the remote Repository. Now let’s push our Repository to the remote one:

After pushing the remote Repository should be listed in your “Mercurial Repositories” View:

We can do a short test if there’s the same on the remote server then in your workspace-repository.

Try to Pull from the remote Server:

there’s nothing to pull:

that’s all: you have successfully installed mercurial-server, managed the users and created a new project 🙂

The overview of my blog seriesabout DVCS can be found here.