# http web serve for mercurial

2015/06/24 18:30

#Serving over HTTP using CGI

The simplest way to host one or more repositories in a permanent way is to use a web server and Mercurial's CGI support. 5 comments

Depending on how ambitious you are, configuring Mercurial's CGI interface can take anything from a few moments to several hours. No comments

We'll begin with the simplest of examples, and work our way towards a more complex configuration. Even for the most basic case, you're almost certainly going to need to read and modify your web server's configuration. No comments

High pain tolerance required Configuring a web server is a complex, fiddly, and highly system-dependent activity. I can't possibly give you instructions that will cover anything like all of the cases you will encounter. Please use your discretion and judgment in following the sections below. Be prepared to make plenty of mistakes, and to spend a lot of time reading your server's error logs. No comments

If you don't have a strong stomach for tweaking configurations over and over, or a compelling need to host your own services, you might want to try one of the public hosting services that I mentioned earlier. No comments

##Web server configuration checklist webserber 配置检查列表

Before you continue, do take a few moments to check a few aspects of your system's setup. 1 comment

Do you have a web server installed at all? Mac OS X and some Linux distributions ship with Apache, but many other systems may not have a web server installed. No comments

If you have a web server installed, is it actually running? On most systems, even if one is present, it will be disabled by default. No comments

Is your server configured to allow you to run CGI programs in the directory where you plan to do so? Most servers default to explicitly disabling the ability to run CGI programs. No comments

If you don't have a web server installed, and don't have substantial experience configuring Apache, you should consider using the lighttpd web server instead of Apache. Apache has a well-deserved reputation for baroque and confusing configuration. While lighttpd is less capable in some ways than Apache, most of these capabilities are not relevant to serving Mercurial repositories. And lighttpd is undeniably much easier to get started with than Apache. 2 comments

##Basic CGI configuration 基本的CGI配置

On Unix-like systems, it's common for users to have a subdirectory named something like public_html in their home directory, from which they can serve up web pages. A file named foo in this directory will be accessible at a URL of the form http://www.example.com/username/foo. 2 comments

To get started, find the hgweb.cgi script that should be present in your Mercurial installation. If you can't quickly find a local copy on your system, simply download one from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi. 2 comments

You'll need to copy this script into your public_html directory, and ensure that it's executable. No comments

cp .../hgweb.cgi ~/public_html
chmod 755 ~/public_html/hgweb.cgi


The 755 argument to chmod is a little more general than just making the script executable: it ensures that the script is executable by anyone, and that “group” and “other” write permissions are not set. If you were to leave those write permissions enabled, Apache's suexec subsystem would likely refuse to execute the script. In fact, suexec also insists that the directory in which the script resides must not be writable by others. No comments

chmod 的755参数只是一个通常的设置，目的是确保这个脚本可以被任何人执行，不过group 和 other 写的权限并没有被设置。如果你将那些写的权限开放，apache的suexec 子系统将会拒绝执行这个脚本。事实上，suexec坚持这个文件夹中的script不应当被others写入。

chmod 755 ~/public_html


##What could possibly go wrong? 为什么会出现错误？

Once you've copied the CGI script into place, go into a web browser, and try to open the URL http://myhostname/~myuser/hgweb.cgi, but brace yourself for instant failure. There's a high probability that trying to visit this URL will fail, and there are many possible reasons for this. In fact, you're likely to stumble over almost every one of the possible errors below, so please read carefully. The following are all of the problems I ran into on a system running Fedora 7, with a fresh installation of Apache, and a user account that I created specially to perform this exercise. 1 comment

Your web server may have per-user directories disabled. If you're using Apache, search your config file for a UserDir directive. If there's none present, per-user directories will be disabled. If one exists, but its value is disabled, then per-user directories will be disabled. Otherwise, the string after UserDir gives the name of the subdirectory that Apache will look in under your home directory, for example public_html. No comments

Your file access permissions may be too restrictive. The web server must be able to traverse your home directory and directories under your public_html directory, and read files under the latter too. Here's a quick recipe to help you to make your permissions more appropriate. No comments

chmod 755 ~
find ~/public_html -type d -print0 | xargs -0r chmod 755
find ~/public_html -type f -print0 | xargs -0r chmod 644


The other possibility with permissions is that you might get a completely empty window when you try to load the script. In this case, it's likely that your access permissions are too permissive. Apache's suexec subsystem won't execute a script that's group- or world-writable, for example. No comments

Your web server may be configured to disallow execution of CGI programs in your per-user web directory. Here's Apache's default per-user configuration from my Fedora system. No comments

<Directory /home/*/public_html>
AllowOverride FileInfo AuthConfig Limit
<Limit GET POST OPTIONS>
Order allow,deny
Allow from all
</Limit>
<LimitExcept GET POST OPTIONS>
Order deny,allow Deny from all
</LimitExcept>
</Directory>


If you find a similar-looking Directory group in your Apache configuration, the directive to look at inside it is Options. Add ExecCGI to the end of this list if it's missing, and restart the web server. No comments 这段没看懂 #TODO

If you find that Apache serves you the text of the CGI script instead of executing it, you may need to either uncomment (if already present) or add a directive like this. No comments

AddHandler cgi-script .cgi


The next possibility is that you might be served with a colourful Python backtrace claiming that it can't import a mercurial-related module. This is actually progress! The server is now capable of executing your CGI script. This error is only likely to occur if you're running a private installation of Mercurial, instead of a system-wide version. Remember that the web server runs the CGI program without any of the environment variables that you take for granted in an interactive session. If this error happens to you, edit your copy of hgweb.cgi and follow the directions inside it to correctly set your PYTHONPATH environment variable. 3 comments

Finally, you are certain to be served with another colourful Python backtrace: this one will complain that it can't find /path/to/repository. Edit your hgweb.cgi script and replace the /path/to/repository string with the complete path to the repository you want to serve up. 3 comments

At this point, when you try to reload the page, you should be presented with a nice HTML view of your repository's history. Whew! 1 comment

##Configuring lighttpd 配置 lighttpd

To be exhaustive in my experiments, I tried configuring the increasingly popular lighttpd web server to serve the same repository as I described with Apache above. I had already overcome all of the problems I outlined with Apache, many of which are not server-specific. As a result, I was fairly sure that my file and directory permissions were good, and that my hgweb.cgi script was properly edited. 1 comment

Once I had Apache running, getting lighttpd to serve the repository was a snap (in other words, even if you're trying to use lighttpd, you should read the Apache section). I first had to edit the mod_access section of its config file to enable mod_cgi and mod_userdir, both of which were disabled by default on my system. I then added a few lines to the end of the config file, to configure these modules. No comments

userdir.path = "public_html"
cgi.assign = (".cgi" => "" )


With this done, lighttpd ran immediately for me. If I had configured lighttpd before Apache, I'd almost certainly have run into many of the same system-level configuration problems as I did with Apache. However, I found lighttpd to be noticeably easier to configure than Apache, even though I've used Apache for over a decade, and this was my first exposure to lighttpd. 1 comment

##Sharing multiple repositories with one CGI script 使用CGI SCRIPT同时分享多个仓库

The hgweb.cgi script only lets you publish a single repository, which is an annoying restriction. If you want to publish more than one without wracking yourself with multiple copies of the same script, each with different names, a better choice is to use the hgwebdir.cgi script. 3 comments

hgweb.cgi脚本只能让你发布一个仓库,这当然是一个很讨厌的限制。如果你不想每次发布一个仓库的时候只是，复制hgweb.cgi然后改个名字的话，一个更好的方法是使用hgwebdir.cgi脚本

The procedure to configure hgwebdir.cgi is only a little more involved than for hgweb.cgi. First, you must obtain a copy of the script. If you don't have one handy, you can download a copy from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi. 3 comments

You'll need to copy this script into your public_html directory, and ensure that it's executable. No comments

cp .../hgwebdir.cgi ~/public_html
chmod 755 ~/public_html ~/public_html/hgwebdir.cgi


With basic configuration out of the way, try to visit http://myhostname/~myuser/hgwebdir.cgi in your browser. It should display an empty list of repositories. If you get a blank window or error message, try walking through the list of potential problems in the section called “What could possibly go wrong?”. No comments

The hgwebdir.cgi script relies on an external configuration file. By default, it searches for a file named hgweb.config in the same directory as itself. You'll need to create this file, and make it world-readable. The format of the file is similar to a Windows “ini” file, as understood by Python's ConfigParser [web:configparser] module. 1 comment

The easiest way to configure hgwebdir.cgi is with a section named collections. This will automatically publish every repository under the directories you name. The section should look like this: 1 comment

[collections]
/my/root = /my/root


Mercurial interprets this by looking at the directory name on the right hand side of the “=” sign; finding repositories in that directory hierarchy; and using the text on the left to strip off matching text from the names it will actually list in the web interface. The remaining component of a path after this stripping has occurred is called a “virtual path”. No comments

mercurial 会依据等号右边的路径进行查找；找到右键路径相对应的文件结构，然后在web 地址中匹配左边的路径。右边路径中去除左边剩余的部分叫做“虚拟路径”（每太看懂）

Given the example above, if we have a repository whose local path is /my/root/this/repo, the CGI script will strip the leading /my/root from the name, and publish the repository with a virtual path of this/repo. If the base URL for our CGI script is http://myhostname/~myuser/hgwebdir.cgi, the complete URL for that repository will be http://myhostname/~myuser/hgwebdir.cgi/this/repo. No comments

If we replace /my/root on the left hand side of this example with /my, then hgwebdir.cgi will only strip off /my from the repository name, and will give us a virtual path of root/this/repo instead of this/repo. No comments

The hgwebdir.cgi script will recursively search each directory listed in the collections section of its configuration file, but it will not recurse into the repositories it finds. No comments

hgwebdir.cgi脚本循环搜索config文件collections 区块中列出的所有仓库，但是不会搜索仓库内部的文件

The collections mechanism makes it easy to publish many repositories in a “fire and forget” manner. You only need to set up the CGI script and configuration file one time. Afterwards, you can publish or unpublish a repository at any time by simply moving it into, or out of, the directory hierarchy in which you've configured hgwebdir.cgi to look. No comments

collections机制可以非常方便的管理多个仓库。你只需要在一个配置文件中设置一次即可。之后你可以在任何时间发布或者不发布某个仓库

##Explicitly specifying which repositories to publish 完整的设置某个仓库

In addition to the collections mechanism, the hgwebdir.cgi script allows you to publish a specific list of repositories. To do so, create a paths section, with contents of the following form. No comments

[paths]
repo1 = /my/path/to/some/repo
repo2 = /some/path/to/another


In this case, the virtual path (the component that will appear in a URL) is on the left hand side of each definition, while the path to the repository is on the right. Notice that there does not need to be any relationship between the virtual path you choose and the location of a repository in your filesystem. No comments

If you wish, you can use both the collections and paths mechanisms simultaneously in a single configuration file. No comments

[Note] Beware duplicate virtual paths If several repositories have the same virtual path, hgwebdir.cgi will not report an error. Instead, it will behave unpredictably. No comments 注意，避免重复的虚拟路径 如果多个仓库有一个相同的虚拟路径，hgwebdir.cgi将会报告一错误。而且不能正常工作

Mercurial's web interface lets users download an archive of any revision. This archive will contain a snapshot of the working directory as of that revision, but it will not contain a copy of the repository data. No comments

Mercurial 的web 界面允许用户 下载某个版本的某个归档文件。这个归档文件包含了工作路径中某个版本的快照，但是他不会包含仓库内的数据（即纯文件，不包括历史，会小很多）

By default, this feature is not enabled. To enable it, you'll need to add an allow_archive item to the web section of your ~/.hgrc; see below for details. No comments

##Web configuration options web 配置的一些参数

Mercurial's web interfaces (the hg serve command, and the hgweb.cgi and hgwebdir.cgi scripts) have a number of configuration options that you can set. These belong in a section named web. No comments

mercurial 的web 接口（hg server 命令，以及 hgweb.cgi 以及 hgwebdir.cgi脚本）可以设置很多参数，下面是一些在web区块的参数

• allow_archive: Determines which (if any) archive download mechanisms Mercurial supports. If you enable this feature, users of the web interface will be able to download an archive of whatever revision of a repository they are viewing. To enable the archive feature, this item must take the form of a sequence of words drawn from the list below. No comments 允许归档

• bz2: A tar archive, compressed using bzip2 compression. This has the best compression ratio, but uses the most CPU time on the server. bz2压缩归档

• gz: A tar archive, compressed using gzip compression. No comments

• zip: A zip archive, compressed using LZW compression. This format has the worst compression ratio, but is widely used in the Windows world. zip 归档

If you provide an empty list, or don't have an allow_archive entry at all, this feature will be disabled. Here is an example of how to enable all three supported formats. No comments

[web]
allow_archive = bz2 gz zip

• allowpull: Boolean. Determines whether the web interface allows remote users to hg pull and hg clone this repository over HTTP. If set to no or false, only the “human-oriented” portion of the web interface is available. 3 comments 允许pull boolean 类型，决定用户是否可以通过hg pull 或者hg clone 通过http协议进行仓库访问，如果是no 或者false，那么只能通过网页的方式进行访问

• contact: String. A free-form (but preferably brief) string identifying the person or group in charge of the repository. This often contains the name and email address of a person or mailing list. It often makes sense to place this entry in a repository's own .hg/hgrc file, but it can make sense to use in a global ~/.hgrc if every repository has a single maintainer. contact: string类型 这里设定有哪些人或者组来负责这个仓库。这里通常设置name 名字，或者email地址。通常情况下推荐在每个仓库的.hg/hgrc文件中进行设置，这样可以确保每个仓库的负责人都不同，当然如果所有仓库的负责人都相同的话也可以在全局的设置文件~/.hgrc中进行设置

• maxchanges: Integer. The default maximum number of changesets to display in a single page of output. maxchanges: int类型。默认的每页面显示的修改集的个数

• maxfiles: Integer. The default maximum number of modified files to display in a single page of output. maxfiles: int 默认每页显示的修改的文件数

• stripes: Integer. If the web interface displays alternating “stripes” to make it easier to visually align rows when you are looking at a table, this number controls the number of rows in each stripe. stripes: int类型，也是页面显示的设置，没吊用

• style: Controls the template Mercurial uses to display the web interface. Mercurial ships with several web templates. style: 控制页面显示使用哪个模板风格，没吊用

gitweb emulates the visual style of git's web interface. No comments

monoblue uses solid blues and greys. No comments

paper is the default. No comments

spartan was the default for a long time. No comments 上面是支持的几种不同的样式风格

You can also specify a custom template of your own; see Chapter 11, Customizing the output of Mercurial for details. Here, you can see how to enable the gitweb style. No comments

[web]
style = gitweb

• templates: Path. The directory in which to search for template files. By default, Mercurial searches in the directory in which it was installed. templates:搜索显示模板的文件夹地址

If you are using hgwebdir.cgi, you can place a few configuration items in a web section of the hgweb.config file instead of a ~/.hgrc file, for convenience. These items are motd and style. 2 comments

##Options specific to an individual repository 针对每个仓库设置

A few web configuration items ought to be placed in a repository's local .hg/hgrc, rather than a user's or global ~/.hgrc.

• description: String. A free-form (but preferably brief) string that describes the contents or purpose of the repository. No comments仓库的描述

• name: String. The name to use for the repository in the web interface. This overrides the default name, which is the last component of the repository's path. No comments 在web接口中使用的仓库的名字，默认是仓库路径的文件夹名字

##Options specific to the hg serve command 跟hg server 命令相关的参数

Some of the items in the web section of a ~/.hgrc file are only for use with the hg serve command. No comments

• accesslog: Path. The name of a file into which to write an access log. By default, the hg serve command writes this information to standard output, not to a file. Log entries are written in the standard “combined” file format used by almost all web servers. accesslog ：accesslog路径 用来存放访问log的文件路径

• address: String. The local address on which the server should listen for incoming connections. By default, the server listens on all addresses. server的本地地址 应该没有什么用？

• errorlog: Path. The name of a file into which to write an error log. By default, the hg serve command writes this information to standard error, not to a file. No comments 错误日志的路径

• ipv6: Boolean. Whether to use the IPv6 protocol. By default, IPv6 is not used. No comments 是否启用ipv6 默认是不启动

• port: Integer. The TCP port number on which the server should listen. The default port number used is 8000. No comments 端口 默认是8000

##Choosing the right ~/.hgrc file to add web items to 选择正确的~/.hgrc文件添加web条目

It is important to remember that a web server like Apache or lighttpd will run under a user ID that is different to yours. CGI scripts run by your server, such as hgweb.cgi, will usually also run under that user ID. No comments

If you add web items to your own personal ~/.hgrc file, CGI scripts won't read that ~/.hgrc file. Those settings will thus only affect the behavior of the hg serve command when you run it. To cause CGI scripts to see your settings, either create a ~/.hgrc file in the home directory of the user ID that runs your web server, or add those settings to a system-wide hgrc file. 3 comments

##System-wide configuration 系统界别的设置

On Unix-like systems shared by multiple users (such as a server to which people publish changes), it often makes sense to set up some global default behaviors, such as what theme to use in web interfaces. No comments

If a file named /etc/mercurial/hgrc exists, Mercurial will read it at startup time and apply any configuration settings it finds in that file. It will also look for files ending in a .rc extension in a directory named /etc/mercurial/hgrc.d, and apply any configuration settings it finds in each of those files. No comments

## Making Mercurial more trusting 使mercurial更加信任

One situation in which a global hgrc can be useful is if users are pulling changes owned by other users. By default, Mercurial will not trust most of the configuration items in a .hg/hgrc file inside a repository that is owned by a different user. If we clone or pull changes from such a repository, Mercurial will print a warning stating that it does not trust their .hg/hgrc. No comments 没什么吊用 不翻译了

If everyone in a particular Unix group is on the same team and should trust each other's configuration settings, or we want to trust particular users, we can override Mercurial's skeptical defaults by creating a system-wide hgrc file such as the following: No comments

# Save this as e.g. /etc/mercurial/hgrc.d/trust.rc
[trusted]
# Trust all entries in any hgrc file owned by the "editors" or
# "www-data" groups.
groups = editors, www-data

# Trust entries in hgrc files owned by the following users.
users = apache, bobo


0
2 收藏

0 评论
2 收藏
0