hgbook
changeset 211:b461d7ead9e1
Start to document hgwebdir.cgi.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue May 08 17:00:44 2007 -0700 (2007-05-08) |
parents | 27b2c7c46af3 |
children | ef8a5e393103 |
files | en/99book.bib en/collab.tex |
line diff
1.1 --- a/en/99book.bib Wed Apr 25 15:23:44 2007 -0700 1.2 +++ b/en/99book.bib Tue May 08 17:00:44 2007 -0700 1.3 @@ -68,3 +68,8 @@ 1.4 title = {PuTTY---open source ssh client for Windows}, 1.5 note = {\url{http://www.chiark.greenend.org.uk/~sgtatham/putty/}}, 1.6 } 1.7 + 1.8 +@Misc{web:configparser, 1.9 + title = {\texttt{ConfigParser}---Configuration file parser}, 1.10 + note = {\url{http://docs.python.org/lib/module-ConfigParser.html}}, 1.11 +}
2.1 --- a/en/collab.tex Wed Apr 25 15:23:44 2007 -0700 2.2 +++ b/en/collab.tex Tue May 08 17:00:44 2007 -0700 2.3 @@ -749,10 +749,22 @@ 2.4 directory, and ensure that it's executable. 2.5 \begin{codesample2} 2.6 cp .../hgweb.cgi ~/public_html 2.7 - chmod +x ~/public_html/hgweb.cgi 2.8 + chmod 755 ~/public_html/hgweb.cgi 2.9 +\end{codesample2} 2.10 +The \texttt{755} argument to \command{chmod} is a little more general 2.11 +than just making the script executable: it ensures that the script is 2.12 +executable by anyone, and that ``group'' and ``other'' write 2.13 +permissions are \emph{not} set. If you were to leave those write 2.14 +permissions enabled, Apache's \texttt{suexec} subsystem would likely 2.15 +refuse to execute the script. In fact, \texttt{suexec} also insists 2.16 +that the \emph{directory} in which the script resides must not be 2.17 +writable by others. 2.18 +\begin{codesample2} 2.19 + chmod 755 ~/public_html 2.20 \end{codesample2} 2.21 2.22 \subsubsection{What could \emph{possibly} go wrong?} 2.23 +\label{sec:collab:wtf} 2.24 2.25 Once you've copied the CGI script into place, go into a web browser, 2.26 and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi}, 2.27 @@ -762,7 +774,7 @@ 2.28 over almost every one of the possible errors below, so please read 2.29 carefully. The following are all of the problems I ran into on a 2.30 system running Fedora~7, with a fresh installation of Apache, and a 2.31 -user account that I created specially. 2.32 +user account that I created specially to perform this exercise. 2.33 2.34 Your web server may have per-user directories disabled. If you're 2.35 using Apache, search your config file for a \texttt{UserDir} 2.36 @@ -850,11 +862,12 @@ 2.37 script was properly edited. 2.38 2.39 Once I had Apache running, getting \texttt{lighttpd} to serve the 2.40 -repository was a snap. I first had to edit the \texttt{mod\_access} 2.41 -section of the config file to enable \texttt{mod\_cgi} and 2.42 -\texttt{mod\_userdir}, both of which were disabled by default on my 2.43 -system. I then added a few lines to the end of the config file, to 2.44 -configure these modules. 2.45 +repository was a snap (in other words, even if you're trying to use 2.46 +\texttt{lighttpd}, you should read the Apache section). I first had 2.47 +to edit the \texttt{mod\_access} section of its config file to enable 2.48 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were 2.49 +disabled by default on my system. I then added a few lines to the end 2.50 +of the config file, to configure these modules. 2.51 \begin{codesample2} 2.52 userdir.path = "public_html" 2.53 cgi.assign = ( ".cgi" => "" ) 2.54 @@ -866,6 +879,77 @@ 2.55 easier to configure than Apache, even though I've used Apache for over 2.56 a decade, and this was my first exposure to \texttt{lighttpd}. 2.57 2.58 +\subsection{Sharing multiple repositories with one CGI script} 2.59 + 2.60 +The \sfilename{hgweb.cgi} script only lets you publish a single 2.61 +repository, which is an annoying restriction. If you want to publish 2.62 +more than one without wracking yourself with multiple copies of the 2.63 +same script, each with different names, a better choice is to use the 2.64 +\sfilename{hgwebdir.cgi} script. 2.65 + 2.66 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little 2.67 +more involved than for \sfilename{hgweb.cgi}. First, you must obtain 2.68 +a copy of the script. If you don't have one handy, you can download a 2.69 +copy from the master Mercurial repository at 2.70 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}. 2.71 + 2.72 +You'll need to copy this script into your \dirname{public\_html} 2.73 +directory, and ensure that it's executable. 2.74 +\begin{codesample2} 2.75 + cp .../hgwebdir.cgi ~/public_html 2.76 + chmod 755 ~/public_html ~/public_html/hgwebdir.cgi 2.77 +\end{codesample2} 2.78 +With basic configuration out of the way, try to visit 2.79 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser. It 2.80 +should display an empty list of repositories. If you get a blank 2.81 +window or error message, try walking through the list of potential 2.82 +problems in section~\ref{sec:collab:wtf}. 2.83 + 2.84 +The \sfilename{hgwebdir.cgi} script relies on an external 2.85 +configuration file. By default, it searches for a file named 2.86 +\sfilename{hgweb.config} in the same directory as itself. You'll need 2.87 +to create this file, and make it world-readable. The format of the 2.88 +file is similar to a Windows ``ini'' file, as understood by Python's 2.89 +\texttt{ConfigParser}~\cite{web:configparser} module. 2.90 + 2.91 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a 2.92 +section named \texttt{collections}. This will automatically publish 2.93 +\emph{every} repository under the directories you name. The section 2.94 +should look like this: 2.95 +\begin{codesample2} 2.96 + [collections] 2.97 + /my/root = /my/root 2.98 +\end{codesample2} 2.99 +Mercurial interprets this by looking at the directory name on the 2.100 +\emph{right} hand side of the ``\texttt{=}'' sign; finding 2.101 +repositories in that directory hierarchy; and using the text on the 2.102 +\emph{left} to strip off matching text from the names it will actually 2.103 +list in the web interface. 2.104 + 2.105 +Given the example above, if we have a repository whose local path is 2.106 +\dirname{/my/root/this/repo}, the CGI script will strip the leading 2.107 +\dirname{/my/root} from the name, and publish the repository as 2.108 +\dirname{this/repo}. If the base URL for our CGI script is 2.109 +\url{http://myhostname/~myuser/hgwebdir.cgi}, the URL for the 2.110 +repository will be 2.111 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}. 2.112 + 2.113 +If we replace \dirname{/my/root} on the left hand side of this example 2.114 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off 2.115 +\dirname{/my} from the repository name, and will publish it as 2.116 +\dirname{root/this/repo} instead of \dirname{this/repo}. 2.117 + 2.118 +The \sfilename{hgwebdir.cgi} script will recursively search each 2.119 +directory listed in the \texttt{collections} section of its 2.120 +configuration file, but it will \texttt{not} recurse into the 2.121 +repositories it finds. 2.122 + 2.123 +The \texttt{collections} mechanism makes it easy to publish many 2.124 +repositories in a ``fire and forget'' manner. You only need to set up 2.125 +the CGI script and configuration file one time. Afterwards, you can 2.126 +publish or unpublish a repository at any time by simply moving it 2.127 +into, or out of, the directory hierarchy in which you've configured 2.128 +\sfilename{hgwebdir.cgi} to look. 2.129 2.130 %%% Local Variables: 2.131 %%% mode: latex