Differences between revisions 1 and 45 (spanning 44 versions)
Revision 1 as of 2005-08-31 07:26:25
Size: 3893
Comment:
Revision 45 as of 2009-03-19 09:54:09
Size: 14457
Comment: This issue should be presented in the main text, not only in troubleshooting
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Publishing Mercurial repositories == = Publishing Mercurial Repositories =
Line 5: Line 5:
There are four (!) ways to publish a repository over HTTP, of which the first two below are most worth considering:

 * Use the `hgweb.cgi` CGI script. This is a simply way to quickly publish a single repository.
 * Use the `hgwebdir.cgi` CGI script. This lets you publish multiple repositories easily, but initial setup can be a bit of work.
 * Make the plain repository available. This uses a much slower, less reliable protocol, called `old-http`. We won't cover it here.
 * Use the {{{hg serve}}} command. This is single threaded. Not recommended except for temporary situations.

== Publishing a single repository ==

The `hgweb.cgi` CGI script is simple to use. You will find it in the root of your Mercurial tree. Copy it to a directory that your web server will handle CGI scripts in, rename it to `index.cgi` if you want, then edit its contents, and you're done.
The following two methods are the most recommended for publishing repositories over HTTP:

 * Use the `hgweb.cgi` script. This is a simple way to quickly [#single publish a single repository].
 * Use the `hgwebdir.cgi` script. This lets you [#multiple publish multiple repositories] easily, but initial setup can be a bit of work.

Less desirable are the following:

 * Use the `hg serve` command. This is Mercurial's [:hgserve:built-in Web server]. It is not really recommended except for temporary situations where you need to publish a repository for a few minutes, for example to pull changes from a laptop.
 * Make the plain repository available. This uses a much slower, less reliable protocol, called `static-http`. We won't cover it here, see ["StaticHTTP"] instead.

For private or restricted-access repositories, some other options exist and these are covered elsewhere:

 * [:SharedSSH:Shared repositories over SSH]
 * HTTPS with authentication certificates
 * NFS

----

[[TableOfContents(2)]]

[[Anchor(introduction)]]
== Introduction and Prerequisites ==

In this document we assume that repositories reside in the `/home/user/hg` directory. For example, a repository called `myproject` would reside in `/home/user/hg/myproject`.

To implement the mechanisms described in this document, you will need the following:

 * Some control over the behaviour of the Web server you use.
 * (Optional) control over the DNS domain you use.

With control over DNS, such as that provided with various Web hosting service control panels, you should be able to set up a subdomain; this makes the URL of your repositories a little tidier, so that `http://hg.example.com/myproject` can be used instead of `http://www.example.com/hgwebdir.cgi/myproject`, for example.

Such an approach, known as virtual hosting, is entirely optional. To implement it for the fictional `example.com`, a CNAME record for `hg.example.com` would be defined for the same address as that already used by the Web server.

[[Anchor(single)]]
== Publishing a Single Repository ==

To publish a single repository, perform the following steps:

 1. Find the `hgweb.cgi` script in the root of your Mercurial source tree.
 1. Copy it to a directory that is configured for CGI scripts in your Web server.
 1. Rename it to `index.cgi` if you want, then edit its contents.

If Mercurial is not installed system-wide, uncomment and edit the Python path in `hgweb.cgi` (or `index.cgi`) as indicated:

{{{
# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")
}}}

You will need to edit the call to `hgweb.hgweb` as indicated in the following example:

{{{
h = hgweb.hgweb("/home/user/hg/myproject", "My Project")
}}}
Line 18: Line 64:
== Publishing multiple repositories ==

The `hgwebdir.cgi` CGI script takes some work to initially set up, but once it's working, it lets you publish new repositories easily and cheaply. Its advantage is that to publish a repository, you simply place a clone in a particular directory, then add one line to a config file to tell the CGI script that it is allowed to publish that repository.

I will describe the setup that BryanOSullivan (me) and ThomasAH use. To mimic our configurations, you will need the following:

 * Control over the web server you use.
 * (Optional) control over the DNS domain you use.

=== Is virtual hosting necessary? ===

Using virtual hosting is entirely optional, and not worth it in the majority of cases. It simply makes URLs a little tidier.

For example, I can serve repositories at http://hg.serpentine.com/mercurial/hg instead of http://www.serpentine.com/hg/hgwebdir.cgi/mercurial/hg.

To do this, I simply have {{{hg.serpentine.com}}} CNAMEd to my web server.
[[Anchor(multiple)]]
== Publishing Multiple Repositories ==

The `hgwebdir.cgi` script takes some work to initially set up, but once it's working, it lets you publish new repositories easily and cheaply. Its advantage is that to publish a repository, you simply place a clone in a particular directory, then add one line to a config file to tell the CGI script that it is allowed to publish that repository.
Line 37: Line 71:
Choose a directory you want to publish from. On my systems, I use {{{/home/bos/hg/share}}}, which you will see below.

Copy `hgwebdir.cgi` in there. Read and edit it, then create a file called `hgweb.config`.

=== Setting up the hgweb.config file ===

Here are the contents of my `hgweb.config` file:
To publish a single repository, perform the following steps:

 1. Find the `hgwebdir.cgi` script in the root of your Mercurial source tree.
 1. Copy it to a directory that is configured for CGI scripts in your Web server. This will be illustrated below using `/home/user/webdir` as this directory.
 1. Edit the contents of the file.

If Mercurial is not installed system-wide, uncomment and edit the Python path in `hgwebdir.cgi` as indicated:

{{{
# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")
}}}

=== Setting up the hgweb.config File ===

In the `/home/user/webdir` directory, create a file called `hgweb.config`. Here are the contents of an `hgweb.config` file:
Line 47: Line 91:
mercurial/bos = mercurial/bos
mercurial/hg = mercurial/hg
mercurial/crew = mercurial/crew
mercurial/tah = mercurial/tah
}}}

The duplication above looks a little silly, but it's telling the CGI script which repositories it is allowed to publish.

=== Configuring Apache ===

Here's the Apache config I use. Description below.
myproject = /home/user/hg/myproject
otherproject = /home/user/hg/otherproject
}}}

This file tells the CGI script which repositories it is allowed to publish and how their published locations map to their actual locations in the filesystem. Note that the keys (on the left) can be paths incorporating `/` characters, and that the values (on the right) can be relative paths to locations within the CGI directory.

== Configuring Apache ==

There are many ways of configuring Apache to run CGI scripts, and a few of the possibilities are provided below. Where the main configuration files are mentioned, you should use the appropriate conventions for your system in defining such files in the `conf.d` and/or `sites-available` directories.

In each example, `hgwebdir.cgi` is mentioned, but the same principles apply to directories hosting the `hgweb.cgi` script.

=== Using a Simple CGI Directory ===

''This example requires access to the main configuration files.''

Here is one way that a CGI directory can be configured:

{{{
Alias /hg /home/user/webdir
<Directory "/home/user/webdir">
    DirectoryIndex hgwebdir.cgi
    AddHandler cgi-script .cgi
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>
}}}

This should permit URLs like `http://www.example.com/hg/` to show the repository browser, although to hide the `hgwebdir.cgi` script name in URLs, more work is required (and is mentioned below).

=== Using Virtual Hosts ===

''This example requires access to the main configuration files.''

Here is an example Apache configuration for publishing repositories at `http://hg.example.com/`. A description follows the example.
Line 61: Line 130:
  ServerName hg.serpentine.com

  ServerAdmin webmaster@serpentine.com
  CustomLog logs/access_log.serpentine combined
  ErrorLog logs/error_log.serpentine
  ServerName hg.example.com

  ServerAdmin webmaster@example.com
  CustomLog logs/access_log.example combined
  ErrorLog logs/error_log.example
Line 68: Line 137:
  RewriteRule (.*) /home/bos/hg/share/hgwebdir.cgi$1

  <Directory "/home/bos/hg/share/">
  RewriteRule (.*) /home/user/webdir/hgwebdir.cgi/$1

  # Or we can use mod_alias for starting CGI script and making URLs "nice":
  # ScriptAliasMatch ^(.*) /home/user/webdir/hgwebdir.cgi/$1

  <Directory "/home/user/webdir/">
Line 80: Line 152:
The {{{ServerName}}} directive matches the hostname I configured earlier.

The next section is just administrative cruft.

The rewrite-related directives tell Apache to turn URIs like {{{/mercurial/hg}}} into {{{/home/bos/hg/share/hgwebdir.cgi/mercurial/hg}}}. This causes Apache to fire up the CGI script, giving it the remainder of the URI as an argument.

Finally, the {{{Directory}}} section lets Apache know that we have a CGI script to look at.
The directives in the above have the following purposes:

 * The `ServerName` directive matches the hostname configured for the domain.
 * The next section (`ServerAdmin` and so on) is just administrative cruft.
 * The rewrite-related directives (`RewriteEngine` and `RewriteRule`) tell Apache to turn URIs ending in `/myproject` into `/home/user/webdir/hgwebdir.cgi/myproject`. This causes Apache to fire up the CGI script, giving it the remainder of the URI as an argument.
 * Finally, the `Directory` section lets Apache know that we have a CGI script to look at.

=== Using a CGI Script with Authentication ===

''This example requires access to the main configuration files.''

Here's an alternative approach that provides global read-only access to the repositories, but requires authentication for pushing:

{{{
ScriptAliasMatch ^/hg(.*) /home/user/webdir/hgwebdir.cgi$1
<Location /hg>
    Allow from all
    Options ExecCGI

    AuthType Digest
    AuthName "Mercurial repositories"
    AuthDigestProvider file
    AuthUserFile /home/user/hg/hgusers
    <LimitExcept GET>
        Require valid-user
    </LimitExcept>
</Location>
}}}

You'll need to add writable users to `/home/user/hg/hgusers` with the `htdigest` command.

=== Using an .htaccess File ===

''This example can be used with pre-configured CGI directories.''

If you may not change the main Apache configuration files, you may still be able to use `.htaccess` file to make URLs nicer, like in the previous section. Here is an `.htaccess` file which sits in the published `webdir` directory on the Web server and redirects `http://www.example.com/hg/*` urls to the `hgwebdir.cgi` script inside that folder. As a result it would no longer be not necessary to mention the CGI script name in URLs: one could use `http://www.example.com/hg/myproject` instead of `http://www.example.com/hg/hgwebdir.cgi/myproject`.

{{{
# Taken from http://www.pmwiki.org/wiki/Cookbook/CleanUrls#samedir
# Used at http://ggap.sf.net/hg/
Options +ExecCGI
RewriteEngine On
#write base depending on where the base url lives
RewriteBase /hg
RewriteRule ^$ hgwebdir.cgi [L]
# Send requests for files that exist to those files.
RewriteCond %{REQUEST_FILENAME} !-f
# Send requests for directories that exist to those directories.
RewriteCond %{REQUEST_FILENAME} !-d
# Send requests to hgwebdir.cgi, appending the rest of url.
RewriteRule (.*) hgwebdir.cgi/$1 [QSA,L]
}}}

A corresponding change in `hgweb.config` can be made to make sure that the nicer urls are used in the HTML produced by the CGI scripts:

{{{
[web]
baseurl = /hg
}}}

Where the CGI scripts are made to appear at the server root (for example, `http://hg.example.com/`), leave the `baseurl` setting blank:

{{{
[web]
baseurl =
}}}

Generally, the value specified should not end with a `/` character.

== Allowing Push ==

Make sure that your repository is writeable by the user running the Apache server (e.g. `www-data'), and that the repository's `.hg/hgrc` file (or the `/home/user/.hgrc` file) contains the allowed users:

{{{
[web]
allow_push = frodo, sam
}}}

This would allow pushing for "frodo" and "sam". You can allow pushing for everyone with

{{{
[web]
allow_push = *
}}}

=== Pushing via http(s) and .htaccess ===

Create an htpasswd file with `htpasswd -c <filename> <username>` and enter the desired password for the username.
Later, you can add more usernames with `htpasswd <filename> <username>`.

Add this to your `.htaccess` file:

{{{
AuthUserFile /path/to/htpasswd
AuthGroupFile /dev/null
AuthName "My Repository"
AuthType Basic
<LimitExcept GET>
Require valid-user
</LimitExcept>
}}}

By default, pushing is only allowed via https. To permit http pushing you have to add this to your repository's `.hg/hgrc` file (or to the `/home/user/.hgrc` file):

{{{
[web]
push_ssl = false
}}}

== Troubleshooting ==

Mercurial is executed on the server by Apache and therefore runs as the Apache user and group. If experiencing flaky behavior, it may be because the CGI script is failing because it does not have enough rights. In that case, you should check the log files, but you can also make some common-sense permissions checks.

There are two ways that problems primarily manifest themselves on the server: either you won't see any repositories at all (indicating missing read or execute permissions) or you won't be able to push to the server (indicating missing write permissions), which gives you the error message:

{{{
abort: ‘http://foo/bar’ does not appear to be an hg repository!
}}}

The best way to solve permissions problems is to grant the required permissions to the Apache group (e.g. www-data on Debian). You should have some familiarity with assigning permissions under Linux/Unix before attempting the following.

Suppose your main user is "john", your web server runs as "www-data" and your repositories are in "/home/john/repositories". Then, execute the following commands to change the group for all files in your repositories on the server and make the files writable to the server process as well as make the home directory readable.

{{{
chown -R john:www-data /home/john/repositories
chmod -R g+rw /home/john/repositories
chmod g+x /home/john/repositories
}}}

For each repository, you will have to make both the repository folder and the .hg folder executable as well:

{{{
chmod g+x /home/john/repositories/rep1
chmod g+x /home/john/repositories/rep1/.hg
}}}

== Putting Useful Information in the Index Page ==

If you get everything working properly, pointing a browser at the CGI script directly should give a list of the repositories you've published. This will be a table containing four columns. Let's say you have published a repository named `lord/rings`. To fill out the first three columns of the index entry for that repository, you will need to edit its `.hg/hgrc` file, and add a new section:

{{{
[web]
contact = Bilbo Baggins
description = My precious!
name = lord/rings
}}}

== Allowing Archive Downloads ==

Make sure that your repository's `.hg/hgrc` file (or the `/home/user/.hgrc` file) contains the `allow_archive` setting:

{{{
[web]
allow_archive = gz, zip, bz2
}}}

This example illustrates how gzip, zip and bzip2 archive formats can be supported. As a result, links should appear in the Web interface corresponding to these archive types.

== What Can Go Wrong? ==

If the version of `hgwebdir.cgi` is newer than the version of Mercurial you have installed, you may experience strange results. This could happen if you use a binary installer for Mercurial, and manually fetch `hgwebcir.cgi` from a source repository. Newer versions of Mercurial support older versions of the cgi scripts, so you usually do not have to upgrade all your cgi installations, though it might be useful.

If you are trying to publish multiple repositories, and you haven't configured Apache to force all accesses to go through the `hgwebdir.cgi` script, you will not be able to access any of the repositories you have published unless you set up a `hgweb.cgi` script in each published repository. Clearly, this defeats the whole point of using `hgwebdir.cgi` in the first place, as you're not saving any effort.

Whatever mechanism you are trying to use, the important thing is to ensure that all accesses go through `hgwebdir.cgi`, so that Apache can pass the rest of the path to it using the `PATH_INFO` environment variable.

== Theming ==

The hgweb interface is completely themable. See the ["Theming"] page for additional instructions on customizing the look of your site.

== See Also ==

 * ["modwsgi"] to do the same using WSGI and Apache
----
CategoryWeb CategoryHowTo

Publishing Mercurial Repositories

The easiest way to share changes with other people using Mercurial is to publish them on the Web. Mercurial lets people pull changes using HTTP.

The following two methods are the most recommended for publishing repositories over HTTP:

  • Use the hgweb.cgi script. This is a simple way to quickly [#single publish a single repository].

  • Use the hgwebdir.cgi script. This lets you [#multiple publish multiple repositories] easily, but initial setup can be a bit of work.

Less desirable are the following:

  • Use the hg serve command. This is Mercurial's [:hgserve:built-in Web server]. It is not really recommended except for temporary situations where you need to publish a repository for a few minutes, for example to pull changes from a laptop.

  • Make the plain repository available. This uses a much slower, less reliable protocol, called static-http. We won't cover it here, see ["StaticHTTP"] instead.

For private or restricted-access repositories, some other options exist and these are covered elsewhere:

  • [:SharedSSH:Shared repositories over SSH]

  • HTTPS with authentication certificates
  • NFS


TableOfContents(2)

Anchor(introduction)

1. Introduction and Prerequisites

In this document we assume that repositories reside in the /home/user/hg directory. For example, a repository called myproject would reside in /home/user/hg/myproject.

To implement the mechanisms described in this document, you will need the following:

  • Some control over the behaviour of the Web server you use.
  • (Optional) control over the DNS domain you use.

With control over DNS, such as that provided with various Web hosting service control panels, you should be able to set up a subdomain; this makes the URL of your repositories a little tidier, so that http://hg.example.com/myproject can be used instead of http://www.example.com/hgwebdir.cgi/myproject, for example.

Such an approach, known as virtual hosting, is entirely optional. To implement it for the fictional example.com, a CNAME record for hg.example.com would be defined for the same address as that already used by the Web server.

Anchor(single)

2. Publishing a Single Repository

To publish a single repository, perform the following steps:

  1. Find the hgweb.cgi script in the root of your Mercurial source tree.

  2. Copy it to a directory that is configured for CGI scripts in your Web server.
  3. Rename it to index.cgi if you want, then edit its contents.

If Mercurial is not installed system-wide, uncomment and edit the Python path in hgweb.cgi (or index.cgi) as indicated:

# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")

You will need to edit the call to hgweb.hgweb as indicated in the following example:

h = hgweb.hgweb("/home/user/hg/myproject", "My Project")

While you could use this mechanism to publish multiple repositories, it requires a little work to configure each copy of the script to have slightly different paths.

Anchor(multiple)

3. Publishing Multiple Repositories

The hgwebdir.cgi script takes some work to initially set up, but once it's working, it lets you publish new repositories easily and cheaply. Its advantage is that to publish a repository, you simply place a clone in a particular directory, then add one line to a config file to tell the CGI script that it is allowed to publish that repository.

3.1. Setting up the CGI script

To publish a single repository, perform the following steps:

  1. Find the hgwebdir.cgi script in the root of your Mercurial source tree.

  2. Copy it to a directory that is configured for CGI scripts in your Web server. This will be illustrated below using /home/user/webdir as this directory.

  3. Edit the contents of the file.

If Mercurial is not installed system-wide, uncomment and edit the Python path in hgwebdir.cgi as indicated:

# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")

3.2. Setting up the hgweb.config File

In the /home/user/webdir directory, create a file called hgweb.config. Here are the contents of an hgweb.config file:

[paths]
myproject = /home/user/hg/myproject
otherproject = /home/user/hg/otherproject

This file tells the CGI script which repositories it is allowed to publish and how their published locations map to their actual locations in the filesystem. Note that the keys (on the left) can be paths incorporating / characters, and that the values (on the right) can be relative paths to locations within the CGI directory.

4. Configuring Apache

There are many ways of configuring Apache to run CGI scripts, and a few of the possibilities are provided below. Where the main configuration files are mentioned, you should use the appropriate conventions for your system in defining such files in the conf.d and/or sites-available directories.

In each example, hgwebdir.cgi is mentioned, but the same principles apply to directories hosting the hgweb.cgi script.

4.1. Using a Simple CGI Directory

This example requires access to the main configuration files.

Here is one way that a CGI directory can be configured:

Alias /hg /home/user/webdir
<Directory "/home/user/webdir">
    DirectoryIndex hgwebdir.cgi
    AddHandler cgi-script .cgi
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>

This should permit URLs like http://www.example.com/hg/ to show the repository browser, although to hide the hgwebdir.cgi script name in URLs, more work is required (and is mentioned below).

4.2. Using Virtual Hosts

This example requires access to the main configuration files.

Here is an example Apache configuration for publishing repositories at http://hg.example.com/. A description follows the example.

<VirtualHost *:80>
  ServerName hg.example.com

  ServerAdmin webmaster@example.com
  CustomLog logs/access_log.example combined
  ErrorLog logs/error_log.example

  RewriteEngine on
  RewriteRule (.*) /home/user/webdir/hgwebdir.cgi/$1

  # Or we can use mod_alias for starting CGI script and making URLs "nice":
  # ScriptAliasMatch ^(.*) /home/user/webdir/hgwebdir.cgi/$1

  <Directory "/home/user/webdir/">
    Order allow,deny
    Allow from all
    AllowOverride All
    Options ExecCGI
    AddHandler cgi-script .cgi
  </Directory>
</VirtualHost>

The directives in the above have the following purposes:

  • The ServerName directive matches the hostname configured for the domain.

  • The next section (ServerAdmin and so on) is just administrative cruft.

  • The rewrite-related directives (RewriteEngine and RewriteRule) tell Apache to turn URIs ending in /myproject into /home/user/webdir/hgwebdir.cgi/myproject. This causes Apache to fire up the CGI script, giving it the remainder of the URI as an argument.

  • Finally, the Directory section lets Apache know that we have a CGI script to look at.

4.3. Using a CGI Script with Authentication

This example requires access to the main configuration files.

Here's an alternative approach that provides global read-only access to the repositories, but requires authentication for pushing:

ScriptAliasMatch ^/hg(.*) /home/user/webdir/hgwebdir.cgi$1
<Location /hg>
    Allow from all
    Options ExecCGI

    AuthType Digest
    AuthName "Mercurial repositories"
    AuthDigestProvider file
    AuthUserFile /home/user/hg/hgusers
    <LimitExcept GET>
        Require valid-user
    </LimitExcept>
</Location>

You'll need to add writable users to /home/user/hg/hgusers with the htdigest command.

4.4. Using an .htaccess File

This example can be used with pre-configured CGI directories.

If you may not change the main Apache configuration files, you may still be able to use .htaccess file to make URLs nicer, like in the previous section. Here is an .htaccess file which sits in the published webdir directory on the Web server and redirects http://www.example.com/hg/* urls to the hgwebdir.cgi script inside that folder. As a result it would no longer be not necessary to mention the CGI script name in URLs: one could use http://www.example.com/hg/myproject instead of http://www.example.com/hg/hgwebdir.cgi/myproject.

# Taken from http://www.pmwiki.org/wiki/Cookbook/CleanUrls#samedir
# Used at http://ggap.sf.net/hg/
Options +ExecCGI
RewriteEngine On
#write base depending on where the base url lives
RewriteBase /hg
RewriteRule ^$ hgwebdir.cgi  [L]
# Send requests for files that exist to those files.
RewriteCond %{REQUEST_FILENAME} !-f
# Send requests for directories that exist to those directories.
RewriteCond %{REQUEST_FILENAME} !-d
# Send requests to hgwebdir.cgi, appending the rest of url.
RewriteRule (.*) hgwebdir.cgi/$1  [QSA,L]

A corresponding change in hgweb.config can be made to make sure that the nicer urls are used in the HTML produced by the CGI scripts:

[web]
baseurl = /hg

Where the CGI scripts are made to appear at the server root (for example, http://hg.example.com/), leave the baseurl setting blank:

[web]
baseurl = 

Generally, the value specified should not end with a / character.

5. Allowing Push

Make sure that your repository is writeable by the user running the Apache server (e.g. www-data'), and that the repository's .hg/hgrc file (or the /home/user/.hgrc` file) contains the allowed users:

[web]
allow_push = frodo, sam

This would allow pushing for "frodo" and "sam". You can allow pushing for everyone with

[web]
allow_push = *

5.1. Pushing via http(s) and .htaccess

Create an htpasswd file with htpasswd -c <filename> <username> and enter the desired password for the username. Later, you can add more usernames with htpasswd <filename> <username>.

Add this to your .htaccess file:

AuthUserFile /path/to/htpasswd
AuthGroupFile /dev/null
AuthName "My Repository"
AuthType Basic
<LimitExcept GET>
Require valid-user
</LimitExcept>

By default, pushing is only allowed via https. To permit http pushing you have to add this to your repository's .hg/hgrc file (or to the /home/user/.hgrc file):

[web]
push_ssl = false

6. Troubleshooting

Mercurial is executed on the server by Apache and therefore runs as the Apache user and group. If experiencing flaky behavior, it may be because the CGI script is failing because it does not have enough rights. In that case, you should check the log files, but you can also make some common-sense permissions checks.

There are two ways that problems primarily manifest themselves on the server: either you won't see any repositories at all (indicating missing read or execute permissions) or you won't be able to push to the server (indicating missing write permissions), which gives you the error message:

abort: ‘http://foo/bar’ does not appear to be an hg repository!

The best way to solve permissions problems is to grant the required permissions to the Apache group (e.g. www-data on Debian). You should have some familiarity with assigning permissions under Linux/Unix before attempting the following.

Suppose your main user is "john", your web server runs as "www-data" and your repositories are in "/home/john/repositories". Then, execute the following commands to change the group for all files in your repositories on the server and make the files writable to the server process as well as make the home directory readable.

chown -R john:www-data /home/john/repositories
chmod -R g+rw /home/john/repositories
chmod g+x /home/john/repositories

For each repository, you will have to make both the repository folder and the .hg folder executable as well:

chmod g+x /home/john/repositories/rep1
chmod g+x /home/john/repositories/rep1/.hg

7. Putting Useful Information in the Index Page

If you get everything working properly, pointing a browser at the CGI script directly should give a list of the repositories you've published. This will be a table containing four columns. Let's say you have published a repository named lord/rings. To fill out the first three columns of the index entry for that repository, you will need to edit its .hg/hgrc file, and add a new section:

[web]
contact = Bilbo Baggins
description = My precious!
name = lord/rings

8. Allowing Archive Downloads

Make sure that your repository's .hg/hgrc file (or the /home/user/.hgrc file) contains the allow_archive setting:

[web]
allow_archive = gz, zip, bz2

This example illustrates how gzip, zip and bzip2 archive formats can be supported. As a result, links should appear in the Web interface corresponding to these archive types.

9. What Can Go Wrong?

If the version of hgwebdir.cgi is newer than the version of Mercurial you have installed, you may experience strange results. This could happen if you use a binary installer for Mercurial, and manually fetch hgwebcir.cgi from a source repository. Newer versions of Mercurial support older versions of the cgi scripts, so you usually do not have to upgrade all your cgi installations, though it might be useful.

If you are trying to publish multiple repositories, and you haven't configured Apache to force all accesses to go through the hgwebdir.cgi script, you will not be able to access any of the repositories you have published unless you set up a hgweb.cgi script in each published repository. Clearly, this defeats the whole point of using hgwebdir.cgi in the first place, as you're not saving any effort.

Whatever mechanism you are trying to use, the important thing is to ensure that all accesses go through hgwebdir.cgi, so that Apache can pass the rest of the path to it using the PATH_INFO environment variable.

10. Theming

The hgweb interface is completely themable. See the ["Theming"] page for additional instructions on customizing the look of your site.

11. See Also

  • ["modwsgi"] to do the same using WSGI and Apache


CategoryWeb CategoryHowTo

PublishingRepositories (last edited 2020-12-06 23:19:24 by PaulBoddie)