1.1 --- a/en/collab.tex	Wed Apr 25 15:23:44 2007 -0700
     1.2 +++ b/en/collab.tex	Tue May 08 17:00:44 2007 -0700
     1.3 @@ -749,10 +749,22 @@
     1.4  directory, and ensure that it's executable.
     1.5  \begin{codesample2}
     1.6    cp .../hgweb.cgi ~/public_html
     1.7 -  chmod +x ~/public_html/hgweb.cgi
     1.8 +  chmod 755 ~/public_html/hgweb.cgi
     1.9 +\end{codesample2}
    1.10 +The \texttt{755} argument to \command{chmod} is a little more general
    1.11 +than just making the script executable: it ensures that the script is
    1.12 +executable by anyone, and that ``group'' and ``other'' write
    1.13 +permissions are \emph{not} set.  If you were to leave those write
    1.14 +permissions enabled, Apache's \texttt{suexec} subsystem would likely
    1.15 +refuse to execute the script.  In fact, \texttt{suexec} also insists
    1.16 +that the \emph{directory} in which the script resides must not be
    1.17 +writable by others.
    1.18 +\begin{codesample2}
    1.19 +  chmod 755 ~/public_html
    1.20  \end{codesample2}
    1.21  
    1.22  \subsubsection{What could \emph{possibly} go wrong?}
    1.23 +\label{sec:collab:wtf}
    1.24  
    1.25  Once you've copied the CGI script into place, go into a web browser,
    1.26  and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
    1.27 @@ -762,7 +774,7 @@
    1.28  over almost every one of the possible errors below, so please read
    1.29  carefully.  The following are all of the problems I ran into on a
    1.30  system running Fedora~7, with a fresh installation of Apache, and a
    1.31 -user account that I created specially.
    1.32 +user account that I created specially to perform this exercise.
    1.33  
    1.34  Your web server may have per-user directories disabled.  If you're
    1.35  using Apache, search your config file for a \texttt{UserDir}
    1.36 @@ -850,11 +862,12 @@
    1.37  script was properly edited.
    1.38  
    1.39  Once I had Apache running, getting \texttt{lighttpd} to serve the
    1.40 -repository was a snap.  I first had to edit the \texttt{mod\_access}
    1.41 -section of the config file to enable \texttt{mod\_cgi} and
    1.42 -\texttt{mod\_userdir}, both of which were disabled by default on my
    1.43 -system.  I then added a few lines to the end of the config file, to
    1.44 -configure these modules.
    1.45 +repository was a snap (in other words, even if you're trying to use
    1.46 +\texttt{lighttpd}, you should read the Apache section).  I first had
    1.47 +to edit the \texttt{mod\_access} section of its config file to enable
    1.48 +\texttt{mod\_cgi} and \texttt{mod\_userdir}, both of which were
    1.49 +disabled by default on my system.  I then added a few lines to the end
    1.50 +of the config file, to configure these modules.
    1.51  \begin{codesample2}
    1.52    userdir.path = "public_html"
    1.53    cgi.assign = ( ".cgi" => "" )
    1.54 @@ -866,6 +879,77 @@
    1.55  easier to configure than Apache, even though I've used Apache for over
    1.56  a decade, and this was my first exposure to \texttt{lighttpd}.
    1.57  
    1.58 +\subsection{Sharing multiple repositories with one CGI script}
    1.59 +
    1.60 +The \sfilename{hgweb.cgi} script only lets you publish a single
    1.61 +repository, which is an annoying restriction.  If you want to publish
    1.62 +more than one without wracking yourself with multiple copies of the
    1.63 +same script, each with different names, a better choice is to use the
    1.64 +\sfilename{hgwebdir.cgi} script.
    1.65 +
    1.66 +The procedure to configure \sfilename{hgwebdir.cgi} is only a little
    1.67 +more involved than for \sfilename{hgweb.cgi}.  First, you must obtain
    1.68 +a copy of the script.  If you don't have one handy, you can download a
    1.69 +copy from the master Mercurial repository at
    1.70 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgwebdir.cgi}.
    1.71 +
    1.72 +You'll need to copy this script into your \dirname{public\_html}
    1.73 +directory, and ensure that it's executable.
    1.74 +\begin{codesample2}
    1.75 +  cp .../hgwebdir.cgi ~/public_html
    1.76 +  chmod 755 ~/public_html ~/public_html/hgwebdir.cgi
    1.77 +\end{codesample2}
    1.78 +With basic configuration out of the way, try to visit
    1.79 +\url{http://myhostname/~myuser/hgwebdir.cgi} in your browser.  It
    1.80 +should display an empty list of repositories.  If you get a blank
    1.81 +window or error message, try walking through the list of potential
    1.82 +problems in section~\ref{sec:collab:wtf}.
    1.83 +
    1.84 +The \sfilename{hgwebdir.cgi} script relies on an external
    1.85 +configuration file.  By default, it searches for a file named
    1.86 +\sfilename{hgweb.config} in the same directory as itself.  You'll need
    1.87 +to create this file, and make it world-readable.  The format of the
    1.88 +file is similar to a Windows ``ini'' file, as understood by Python's
    1.89 +\texttt{ConfigParser}~\cite{web:configparser} module.
    1.90 +
    1.91 +The easiest way to configure \sfilename{hgwebdir.cgi} is with a
    1.92 +section named \texttt{collections}.  This will automatically publish
    1.93 +\emph{every} repository under the directories you name.  The section
    1.94 +should look like this:
    1.95 +\begin{codesample2}
    1.96 +  [collections]
    1.97 +  /my/root = /my/root
    1.98 +\end{codesample2}
    1.99 +Mercurial interprets this by looking at the directory name on the
   1.100 +\emph{right} hand side of the ``\texttt{=}'' sign; finding
   1.101 +repositories in that directory hierarchy; and using the text on the
   1.102 +\emph{left} to strip off matching text from the names it will actually
   1.103 +list in the web interface.
   1.104 +
   1.105 +Given the example above, if we have a repository whose local path is
   1.106 +\dirname{/my/root/this/repo}, the CGI script will strip the leading
   1.107 +\dirname{/my/root} from the name, and publish the repository as
   1.108 +\dirname{this/repo}.  If the base URL for our CGI script is
   1.109 +\url{http://myhostname/~myuser/hgwebdir.cgi}, the URL for the
   1.110 +repository will be
   1.111 +\url{http://myhostname/~myuser/hgwebdir.cgi/this/repo}.
   1.112 +
   1.113 +If we replace \dirname{/my/root} on the left hand side of this example
   1.114 +with \dirname{/my}, then \sfilename{hgwebdir.cgi} will only strip off
   1.115 +\dirname{/my} from the repository name, and will publish it as
   1.116 +\dirname{root/this/repo} instead of \dirname{this/repo}.
   1.117 +
   1.118 +The \sfilename{hgwebdir.cgi} script will recursively search each
   1.119 +directory listed in the \texttt{collections} section of its
   1.120 +configuration file, but it will \texttt{not} recurse into the
   1.121 +repositories it finds.
   1.122 +
   1.123 +The \texttt{collections} mechanism makes it easy to publish many
   1.124 +repositories in a ``fire and forget'' manner.  You only need to set up
   1.125 +the CGI script and configuration file one time.  Afterwards, you can
   1.126 +publish or unpublish a repository at any time by simply moving it
   1.127 +into, or out of, the directory hierarchy in which you've configured
   1.128 +\sfilename{hgwebdir.cgi} to look.
   1.129  
   1.130  %%% Local Variables: 
   1.131  %%% mode: latex