hgbook
diff en/collab.tex @ 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 |
line diff
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