I recently ran through the process of setting up a Mercurial server on IIS 7.5. It was a little painful and not something I would recommend, more so now that Bitbucket is offering free unlimited private repositories for teams with five developers (if Bitbucket isn't your cup of tea, you can find more Mercurial hosters here). If however your client isn't comfortable with having source code hosted externally, you may want to get yourself a Linux/Apache box and follow this comprehensive guide. If you can't do that either, and really want to use IIS 7.5 on Windows 2008 R2, then keep reading (and keep the Advil handy).
This is based on the guide Jeremy Skinner provides on his blog. A few things have changed in Mercurial since it was written however, which prompted me to document exactly what I did differently, and for the sake of completeness, document what I did the same.
Requirements
These aren't requirements so much as just what I used. Later versions may work the same way (although they didn't for Jeremy's guide).
Mercurial is a free, distributed source control management tool. It efficiently handles projects of any size and offers an easy and intuitive interface. Download now Mercurial 5.6 TortoiseHg 5.6 MSI installer - x64 Windows. Mononoke: A Mercurial source control server, specifically designed to support large monorepos.
- Windows 2008 R2
- IIS 7.5
- Python 2.6.6 (32 bit / x86)
- Mercurial 1.7.5 as a Python 2.6 Package (32 bit / x86)
- TortoiseHg 1.1.9.1 (64 bit) (optional, not required for a server)
- Mercurial is a distributed revision-control tool for software developers.It is supported on Microsoft Windows and Unix-like systems, such as FreeBSD, macOS, and Linux. Mercurial's major design goals include high performance and scalability, decentralization, fully distributed collaborative development, robust handling of both plain text and binary files, and advanced branching and merging.
- Installing Mercurial. Installation instructions are provided for Windows, Mac OS X, and Linux. On the server, we are currently using Mercurial 1.5.1. While Mercurial is pretty good at being both backward and forward compatible, we recommend that you use the same version locally. Geeklog's Mercurial repository is available from this URL.
- The first thing we need to do is installing TortoiseHg, a great freeware client to handle Mercurial repositories for all Windows platforms, including Windows Server 2012 and Windows 10. The installation packages, natively available for 32-bit and 64-bit Windows builds, are available free of charge from the project’s official website.
Mercurial is based on Python, and it seems to matter which version of Python is installed. To find out which version of Python Mercurial needs, install TortoiseHg either on the server or the client (or both) and have a look at the About TortoiseHg screen. This version of Mercurial uses Python 2.6.4, but I could only find Python 2.6.6. However, I think as long as the major and minor version numbers match, everything should be fine.
I'm installing Mercurial the Python package, not Mercurial the stand-alone program. Make sure you grab the right one. Mercurial as a Python package means Python can find it easily. I also grabbed the 32 bit version of Python and Mercurial just to get this working as soon as possible. Things may work with the 64 bit versions, but it wasn't something I was willing to fiddle with. If you're feeling brave you might want to give it a go.
TortoiseHg is completely optional on your server. I installed it so I can browse my repositories with it while I'm logged into the server, but if you hardly ever RDP into your server you won't need it. It can be handy to init new repos with it, but that can be accomplished using your local machine and a network share.
IIS 7.5
If your Windows Server doesn't already have IIS 7.5 installed, go ahead and do that now using Server Manager. Make sure CGI and Basic Authentication are installed. (Ignore the other items have checked, they're for other applications.)
Python and Mercurial
Install Python 2.6. It's pretty straight forward and it will end up in a directory like C:Python26 by default. Once that is complete, install the Mercurial Python package. This will look for Python and install itself in the C:Python26Libsite-packages directory.
Web Application
This part of the process is very similar to Jeremy's guide, so I will go over this quickly. If you need more details, Jeremy's effort may have them.
Create an application under the default web site and call it whatever you like, I called it hg like Jeremy did. The physical location is C:inetpubwwwroothg.
Next, go into Handler Mappings and add a Script Map for CGI. Enter *.cgi for the request path, C:Python26python.exe -u '%s' for the executable, and Python for the name.
To test this works, create a simple Python script and save it in the application directory as test.cgi.
Browse to http://localhost/hg/test.cgi to see if it works.
The next thing to do is get a hold of hgweb.cgi, which isn't included in any of the Mercurial installations that were just performed as far as I can tell. One way to grab it is to browse the Mercurial source code here and download it, or you can cut and paste the following and save it to C:inetpubwwwroothghgweb.cgi.
This differs from Jeremy's guide because hgwebdir.cgi and hgweb.cgi were combined in Mercurial 1.6. The hgweb.cgi file now handles both single and multiple repositories.
If you've downloaded the file, open it up and change line 7 to match line 7 above. This is the location of the Mercurial configuration file.
Next, create an empty file and call it hgweb.config. More information will go into it later -- right now an empty file equates to default settings. At this point there should be four files in the C:inetpubwwwroothg directory.
- hgweb.cgi
- hgweb.config
- test.cgi
- web.config (created automatically by the IIS Manager for the CGI handler mapping)
That's enough to get Mercurial running. There's no need to copy the Mercurial library or template directory locally, that's what the Mercurial Python package was for. Browse to http://localhost/hg/hgweb.cgi and the following should be displayed.
Pretty URLs
Jeremy had a great suggestion at this point to create a rewrite rule to eliminate hgweb.cgi from the URL. To do this, URL Rewrite must be added to IIS 7.5 first. The easiest way to do that is to install Web Platform Installer and then install URL Rewrite 2.0 through that.
Now you can follow Jeremy's guide to create the rewrite rule via the interface, or you can cut and paste the <rewrite> section below into your web.config file, just after </handlers>.
Next, edit the hgweb.config file to let Mercurial know how URLs should be generated.
Browse to http://localhost/hg to see the same screen as before.
Test Repo
Now to choose a location for the Mercurial repositories. I went with C:RepositoriesHg. To tell Mercurial about the location, open hgweb.config and modify it like so...
Create a new repo, Test, in the directory and refresh the browser.
You may encounter permission errors when browsing now or later on after some changesets have been pushed. If you do, grant the local IIS_IUSR group permission to read the C:RepositoriesHg directory.
The Test repository should be clonable, but pushing should fail. Over on a client machine, run some quick checks.
All pushes require SSL, lest credentials be transmitted in the clear. For now we'll disable SSL by adding another line to hgweb.config.
Now the push should fail on authorisation.
Modify hgweb.config again to let everyone push.
Try the push again, this time it should work.
Refreshing the browser will show the test commit.
Authentication and Authorisation
Letting everyone push probably isn't a great idea. This is remedied by turning on authentication in IIS and telling Mercurial to authorise. To get started, go back to IIS Manager and enable Basic Authentication. Setting the default domain and realm can also be handy.
Now edit the hgweb.config file to limit who can push.
Pushing another test will result in Mercurial asking for a username and password, authenticated against the domain.
If you get bad gateway errors here the pusher may not have write permissions on the directory. You may want to try giving all pushers write permissions on C:RepositoriesHg. Alternatively, a local group on the server for pushers which has the required permissions may make life easier.
SSL
Passing credentials around in the clear, even on a corporate LAN, is never a good idea. Luckily setting up SSL isn't difficult. First, create a self-signed certificate on the server (or use a real certificate if you have one).
Go into the bindings for the default web site.
Add a new HTTPS binding using the self-signed certificate.
Turn SSL back on for Mercurial by removing the push_ssl = false line from the hgweb.config file.
New in Mercurial 1.7.3 is the automatic checking of certificates against Certification Authorities (CAs). This is a slight problem for self-signed certificates -- the check will always fail. Luckily in Mercurial 1.7.5 there is the ability to skip the check by adding an --insecure option to the command.
To avoid having to type --insecure with every command there are two ways to tell Mercurial to trust the self-signed certificate. The first is to export the certificate in X.509 PEM format and append it to the cacert.pem file in each client's TortoiseHg program files folder. (Firefox can export the certificate and gvim can edit the cacert.pem file.) The second much easier way is to simply add the 'fingerprint' of the server to each client's Mercurial global settings (mercurial.ini). If you're using a build server running under a system account that doesn't have a user profile, the fingerprint can be added to the mercurial.ini file in the TortoiseHg program files folder (the mercurial.ini file may have to be created).
The fingerprint is displayed by Mercurial when using the --insecure option.
Further Security
I haven't tried this yet myself, but if permission is required on a repo by repo basis, try setting up .NET authorisation on each repo folder. It should be possible to set up allow/deny rules on any folder that requires it.
written by Germán Schuager on 19 Mar 2010
In this post I will enumerate the resources and the steps required to setup a Mercurial server under a Windows environment running on top of IIS 7.
This is not as straight-forward as it should be but it is not very difficult either.
You will need to download the following:
- Mercurial 1.5.1 http://bitbucket.org/tortoisehg/thg-winbuild/downloads/mercurial-1.5.1.msi
- Python 2.6 x86 installerhttp://www.python.org/download/releases/2.6/
- if you use another version of Python you will probably end up with a 'Bad magic number' error, as pointed by Lloyd in the comments
- if you use the x64 version you will get some other error messages and hg will not work
- hgwebdir.cgi http://selenic.com/repo/hg/raw-file/ff2704a8ded3/hgwebdir.cgi
- IIS UrlRewriter module http://www.iis.net/expand/URLRewrite (optional but very recommended)
I will split the configuration steps into setting up the file system and configuring IIS.
Setting up the file system
1. Install Mercurial. I will assume the default install path: C:Program Files (x86)Mercurial
2. Install Python. I will assume the default install path: C:Python26
3. Create a folder for your Hg web application. I will assume this path: C:hg
4. Create a subfolder called lib and uncompress the contents of the file C:Program Files (x86)Mercuriallibrary.zip into C:hglib
5. Copy the folder C:Program Files (x86)MercurialTemplates into c:hglib
At this point you should have something like this:
6. Copy the hgwebdir.cgi (link at the top of the post) file into your wep app folder root c:hg and modify it so that it match your Python installation folder and your lib folder. Using my current path assumptions you should end with something like the one in the left of the following picture:
7. Create a folder named repos in c:hgrepos. This folder will contain all our mercurial repositories. For testing purposed now we will create a test repository inside there; just run this from the command line 'hg init c:hgrepostest' (this will create and initialize the test repository)
8. Create a file named hgweb.config at c:hghgweb.config with the following content:
here we are telling Mercurial basically 3 things: where are the repositories that it should serve, everybody can push, and it should allow pushes through non-secure connections (so we don't need to setup https)
Configuring IIS
9. Add a new web application to your 'Default Web Site', name it 'hg' and assign 'c:hg' to its Physical path.
10. Now we need to configure our newly created app to be able to execute Python scripts. Click on the 'Handler Mappings'
then in 'Add Script Map...' from the right menu
and then enter the script extension and Python executable path as shown in the following picture:
11. The final step is to configure Url Rewriter module correctly to allow us to use our repository with a nice URL like this: http://server/hg/test instead of http://server/hg/hgwebdir.cgi/test. For this you need to install the Url Rewriter module either using Web Platform installer or by manually doing so (link at the top of the post).
Mercurial For Windows 10
Once you have Url Rewriter installed, select it from you application Feature View:
Mercurial Server Windows Free
then click on the 'Add Rules...' action from the right side panel and select 'Blank Rule':
and enter the new rule data as shown in the following picture:
And that should be all.
Now try to navigate to http://localhost/hg with your browser and you should see something like this:
Download Mercurial
Just remember to setup authentication if you are going to use this server over the internet. I left this to you since you can use any of the standard IIS authentication methods available.