1.1 --- a/en/collab.tex	Wed Apr 25 13:06:30 2007 -0700
     1.2 +++ b/en/collab.tex	Wed Apr 25 15:23:44 2007 -0700
     1.3 @@ -328,7 +328,10 @@
     1.4  
     1.5  \section{The technical side of sharing}
     1.6  
     1.7 -\subsection{Informal sharing with \hgcmd{serve}}
     1.8 +The remainder of this chapter is devoted to the question of serving
     1.9 +data to your collaborators.
    1.10 +
    1.11 +\section{Informal sharing with \hgcmd{serve}}
    1.12  \label{sec:collab:serve}
    1.13  
    1.14  Mercurial's \hgcmd{serve} command is wonderfully suited to small,
    1.15 @@ -362,7 +365,7 @@
    1.16  This can help you to quickly get acquainted with using commands on
    1.17  network-hosted repositories.
    1.18  
    1.19 -\subsubsection{A few things to keep in mind}
    1.20 +\subsection{A few things to keep in mind}
    1.21  
    1.22  Because it provides unauthenticated read access to all clients, you
    1.23  should only use \hgcmd{serve} in an environment where you either don't
    1.24 @@ -386,7 +389,7 @@
    1.25  correctly, and find out what URL you should send to your
    1.26  collaborators, start it with the \hggopt{-v} option.
    1.27  
    1.28 -\subsection{Using the Secure Shell (ssh) protocol}
    1.29 +\section{Using the Secure Shell (ssh) protocol}
    1.30  \label{sec:collab:ssh}
    1.31  
    1.32  You can pull and push changes securely over a network connection using
    1.33 @@ -402,7 +405,7 @@
    1.34  (If you \emph{are} familiar with ssh, you'll probably find some of the
    1.35  material that follows to be elementary in nature.)
    1.36  
    1.37 -\subsubsection{How to read and write ssh URLs}
    1.38 +\subsection{How to read and write ssh URLs}
    1.39  
    1.40  An ssh URL tends to look like this:
    1.41  \begin{codesample2}
    1.42 @@ -449,7 +452,7 @@
    1.43    ssh://server//absolute/path
    1.44  \end{codesample2}
    1.45  
    1.46 -\subsubsection{Finding an ssh client for your system}
    1.47 +\subsection{Finding an ssh client for your system}
    1.48  
    1.49  Almost every Unix-like system comes with OpenSSH preinstalled.  If
    1.50  you're using such a system, run \Verb|which ssh| to find out if
    1.51 @@ -482,7 +485,7 @@
    1.52    idea).
    1.53  \end{note}
    1.54  
    1.55 -\subsubsection{Generating a key pair}
    1.56 +\subsection{Generating a key pair}
    1.57  
    1.58  To avoid the need to repetitively type a password every time you need
    1.59  to use your ssh client, I recommend generating a key pair.  On a
    1.60 @@ -508,7 +511,7 @@
    1.61  window it's displayed in straight into the
    1.62  \sfilename{authorized\_keys} file.
    1.63  
    1.64 -\subsubsection{Using an authentication agent}
    1.65 +\subsection{Using an authentication agent}
    1.66  
    1.67  An authentication agent is a daemon that stores passphrases in memory
    1.68  (so it will forget passphrases if you log out and log back in again).
    1.69 @@ -531,7 +534,7 @@
    1.70  command acts as the agent.  It adds an icon to your system tray that
    1.71  will let you manage stored passphrases.
    1.72  
    1.73 -\subsubsection{Configuring the server side properly}
    1.74 +\subsection{Configuring the server side properly}
    1.75  
    1.76  Because ssh can be fiddly to set up if you're new to it, there's a
    1.77  variety of things that can go wrong.  Add Mercurial on top, and
    1.78 @@ -648,7 +651,7 @@
    1.79  point, try using the \hggopt{--debug} option to get a clearer picture
    1.80  of what's going on.
    1.81  
    1.82 -\subsubsection{Using compression with ssh}
    1.83 +\subsection{Using compression with ssh}
    1.84  
    1.85  Mercurial does not compress data when it uses the ssh protocol,
    1.86  because the ssh protocol can transparently compress data.  However,
    1.87 @@ -683,9 +686,185 @@
    1.88  and use compression.  This gives you both a shorter name to type and
    1.89  compression, each of which is a good thing in its own right.
    1.90  
    1.91 -\subsection{Serving over HTTP with a CGI script}
    1.92 +\section{Serving over HTTP using CGI}
    1.93  \label{sec:collab:cgi}
    1.94  
    1.95 +Depending on how ambitious you are, configuring Mercurial's CGI
    1.96 +interface can take anything from a few moments to several hours.
    1.97 +
    1.98 +We'll begin with the simplest of examples, and work our way towards a
    1.99 +more complex configuration.  Even for the most basic case, you're
   1.100 +almost certainly going to need to read and modify your web server's
   1.101 +configuration.
   1.102 +
   1.103 +\begin{note}
   1.104 +  Configuring a web server is a complex, fiddly, and highly
   1.105 +  system-dependent activity.  I can't possibly give you instructions
   1.106 +  that will cover anything like all of the cases you will encounter.
   1.107 +  Please use your discretion and judgment in following the sections
   1.108 +  below.  Be prepared to make plenty of mistakes, and to spend a lot
   1.109 +  of time reading your server's error logs.
   1.110 +\end{note}
   1.111 +
   1.112 +\subsection{Web server configuration checklist}
   1.113 +
   1.114 +Before you continue, do take a few moments to check a few aspects of
   1.115 +your system's setup.
   1.116 +
   1.117 +\begin{enumerate}
   1.118 +\item Do you have a web server installed at all?  Mac OS X ships with
   1.119 +  Apache, but many other systems may not have a web server installed.
   1.120 +\item If you have a web server installed, is it actually running?  On
   1.121 +  most systems, even if one is present, it will be disabled by
   1.122 +  default.
   1.123 +\item Is your server configured to allow you to run CGI programs in
   1.124 +  the directory where you plan to do so?  Most servers default to
   1.125 +  explicitly disabling the ability to run CGI programs.
   1.126 +\end{enumerate}
   1.127 +
   1.128 +If you don't have a web server installed, and don't have substantial
   1.129 +experience configuring Apache, you should consider using the
   1.130 +\texttt{lighttpd} web server instead of Apache.  Apache has a
   1.131 +well-deserved reputation for baroque and confusing configuration.
   1.132 +While \texttt{lighttpd} is less capable in some ways than Apache, most
   1.133 +of these capabilities are not relevant to serving Mercurial
   1.134 +repositories.  And \texttt{lighttpd} is undeniably \emph{much} easier
   1.135 +to get started with than Apache.
   1.136 +
   1.137 +\subsection{Basic CGI configuration}
   1.138 +
   1.139 +On Unix-like systems, it's common for users to have a subdirectory
   1.140 +named something like \dirname{public\_html} in their home directory,
   1.141 +from which they can serve up web pages.  A file named \filename{foo}
   1.142 +in this directory will be accessible at a URL of the form
   1.143 +\texttt{http://www.example.com/\~username/foo}.
   1.144 +
   1.145 +To get started, find the \sfilename{hgweb.cgi} script that should be
   1.146 +present in your Mercurial installation.  If you can't quickly find a
   1.147 +local copy on your system, simply download one from the master
   1.148 +Mercurial repository at
   1.149 +\url{http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi}.
   1.150 +
   1.151 +You'll need to copy this script into your \dirname{public\_html}
   1.152 +directory, and ensure that it's executable.
   1.153 +\begin{codesample2}
   1.154 +  cp .../hgweb.cgi ~/public_html
   1.155 +  chmod +x ~/public_html/hgweb.cgi
   1.156 +\end{codesample2}
   1.157 +
   1.158 +\subsubsection{What could \emph{possibly} go wrong?}
   1.159 +
   1.160 +Once you've copied the CGI script into place, go into a web browser,
   1.161 +and try to open the URL \url{http://myhostname/~myuser/hgweb.cgi},
   1.162 +\emph{but} brace yourself for instant failure.  There's a high
   1.163 +probability that trying to visit this URL will fail, and there are
   1.164 +many possible reasons for this.  In fact, you're likely to stumble
   1.165 +over almost every one of the possible errors below, so please read
   1.166 +carefully.  The following are all of the problems I ran into on a
   1.167 +system running Fedora~7, with a fresh installation of Apache, and a
   1.168 +user account that I created specially.
   1.169 +
   1.170 +Your web server may have per-user directories disabled.  If you're
   1.171 +using Apache, search your config file for a \texttt{UserDir}
   1.172 +directive.  If there's none present, per-user directories will be
   1.173 +disabled.  If one exists, but its value is \texttt{disabled}, then
   1.174 +per-user directories will be disabled.  Otherwise, the string after
   1.175 +\texttt{UserDir} gives the name of the subdirectory that Apache will
   1.176 +look in under your home directory, for example \dirname{public\_html}.
   1.177 +
   1.178 +Your file access permissions may be too restrictive.  The web server
   1.179 +must be able to traverse your home directory and directories under
   1.180 +your \dirname{public\_html} directory, and read files under the latter
   1.181 +too.  Here's a quick recipe to help you to make your permissions more
   1.182 +appropriate.
   1.183 +\begin{codesample2}
   1.184 +  chmod 755 ~
   1.185 +  find ~/public_html -type d -print0 | xargs -0r chmod 755
   1.186 +  find ~/public_html -type f -print0 | xargs -0r chmod 644
   1.187 +\end{codesample2}
   1.188 +
   1.189 +The other possibility with permissions is that you might get a
   1.190 +completely empty window when you try to load the script.  In this
   1.191 +case, it's likely that your access permissions are \emph{too
   1.192 +  permissive}.  Apache's \texttt{suexec} subsystem won't execute a
   1.193 +script that's group-~or world-writable, for example.
   1.194 +
   1.195 +Your web server may be configured to disallow execution of CGI
   1.196 +programs in your per-user web directory.  Here's Apache's
   1.197 +default per-user configuration from my Fedora system.
   1.198 +\begin{codesample2}
   1.199 +  <Directory /home/*/public_html>
   1.200 +      AllowOverride FileInfo AuthConfig Limit
   1.201 +      Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec
   1.202 +      <Limit GET POST OPTIONS>
   1.203 +          Order allow,deny
   1.204 +          Allow from all
   1.205 +      </Limit>
   1.206 +      <LimitExcept GET POST OPTIONS>
   1.207 +          Order deny,allow
   1.208 +          Deny from all
   1.209 +      </LimitExcept>
   1.210 +  </Directory>
   1.211 +\end{codesample2}
   1.212 +If you find a similar-looking \texttt{Directory} group in your Apache
   1.213 +configuration, the directive to look at inside it is \texttt{Options}.
   1.214 +Add \texttt{ExecCGI} to the end of this list if it's missing, and
   1.215 +restart the web server.
   1.216 +
   1.217 +If you find that Apache serves you the text of the CGI script instead
   1.218 +of executing it, you may need to either uncomment (if already present)
   1.219 +or add a directive like this.
   1.220 +\begin{codesample2}
   1.221 +  AddHandler cgi-script .cgi
   1.222 +\end{codesample2}
   1.223 +
   1.224 +The next possibility is that you might be served with a colourful
   1.225 +Python backtrace claiming that it can't import a
   1.226 +\texttt{mercurial}-related module.  This is actually progress!  The
   1.227 +server is now capable of executing your CGI script.  This error is
   1.228 +only likely to occur if you're running a private installation of
   1.229 +Mercurial, instead of a system-wide version.  Remember that the web
   1.230 +server runs the CGI program without any of the environment variables
   1.231 +that you take for granted in an interactive session.  If this error
   1.232 +happens to you, edit your copy of \sfilename{hgweb.cgi} and follow the
   1.233 +directions inside it to correctly set your \envar{PYTHONPATH}
   1.234 +environment variable.
   1.235 +
   1.236 +Finally, you are \emph{certain} to by served with another colourful
   1.237 +Python backtrace: this one will complain that it can't find
   1.238 +\dirname{/path/to/repository}.  Edit your \sfilename{hgweb.cgi} script
   1.239 +and replace the \dirname{/path/to/repository} string with the complete
   1.240 +path to the repository you want to serve up.
   1.241 +
   1.242 +At this point, when you try to reload the page, you should be
   1.243 +presented with a nice HTML view of your repository's history.  Whew!
   1.244 +
   1.245 +\subsubsection{Configuring lighttpd}
   1.246 +
   1.247 +To be exhaustive in my experiments, I tried configuring the
   1.248 +increasingly popular \texttt{lighttpd} web server to serve the same
   1.249 +repository as I described with Apache above.  I had already overcome
   1.250 +all of the problems I outlined with Apache, many of which are not
   1.251 +server-specific.  As a result, I was fairly sure that my file and
   1.252 +directory permissions were good, and that my \sfilename{hgweb.cgi}
   1.253 +script was properly edited.
   1.254 +
   1.255 +Once I had Apache running, getting \texttt{lighttpd} to serve the
   1.256 +repository was a snap.  I first had to edit the \texttt{mod\_access}
   1.257 +section of the config file to enable \texttt{mod\_cgi} and
   1.258 +\texttt{mod\_userdir}, both of which were disabled by default on my
   1.259 +system.  I then added a few lines to the end of the config file, to
   1.260 +configure these modules.
   1.261 +\begin{codesample2}
   1.262 +  userdir.path = "public_html"
   1.263 +  cgi.assign = ( ".cgi" => "" )
   1.264 +\end{codesample2}
   1.265 +With this done, \texttt{lighttpd} ran immediately for me.  If I had
   1.266 +configured \texttt{lighttpd} before Apache, I'd almost certainly have
   1.267 +run into many of the same system-level configuration problems as I did
   1.268 +with Apache.  However, I found \texttt{lighttpd} to be noticeably
   1.269 +easier to configure than Apache, even though I've used Apache for over
   1.270 +a decade, and this was my first exposure to \texttt{lighttpd}.
   1.271  
   1.272  
   1.273  %%% Local Variables: