Subversion Repositories WebSVN

Rev

Rev 1103 | Details | Compare with Previous | Last modification | View Log | SVN | RSS feed

Rev Author Line No. Line
539 tarmes 1 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2 
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
3 
<head>
4 
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
5 
  <meta http-equiv="content-script-type" content="text/javascript" />
6 
  <meta http-equiv="content-style-type" content="text/css" />
7 
  <title>WebSVN Installation Guide</title>
624 spetters 8 
  <link rel="stylesheet" type="text/css" href="style.css" />
539 tarmes 9 
</head>
10 
 
11 
<body>
12 
 
13 
<h1>WebSVN Installation Guide</h1>
14 
 
900 quinntaylor 15 
<div id="contents">
539 tarmes 16 
<h2><a name="content"></a>Content</h2>
17 
<ul>
18 
  <li><a href="#why">Why WebSVN?</a></li>
19 
  <li><a href="#installation">Installation</a></li>
1103 quinntaylor 20 
  <li><a href="#addingrepos">Adding Repositories</a><ul>
21 
    <li><a href="#credentials">Credentials</a></li>
22 
    <li><a href="#groups">Groups</a></li>
23 
    <li><a href="#svnclienturls">SVN Client URLs</a></li>
24 
  </ul></li>
539 tarmes 25 
  <li><a href="#colourisation">Colourisation</a></li>
1103 quinntaylor 26 
  <li><a href="#templates">Templates</a></li>
900 quinntaylor 27 
  <li><a href="#multiviews">Mulitviews</a><ul>
28 
    <li><a href="#multiviewsexample">Mulitviews example</a></li>
29 
  </ul></li>
539 tarmes 30 
  <li><a href="#authentication">Access rights and authentication</a></li>
31 
  <li><a href="#problems">Common problems</a></li>
32 
  <li><a href="#license">License</a></li>
33 
</ul>
624 spetters 34 
</div>
539 tarmes 35 
 
36 
<h2><a name="why"></a>Why WebSVN?</h2>
37 
 
1103 quinntaylor 38 
<p>WebSVN offers a view of your subversion repositories that's been designed to reflect the Subversion methodology. You can view the log of any file or directory and see a list of all the files changed, added or deleted in any given revision. You can also view the differences between versions of a file to see exactly what was changed in a particular revision.</p>
539 tarmes 39 
 
1103 quinntaylor 40 
<p>WebSVN offers the following key features:</p>
539 tarmes 41 
 
42 
<ul>
1103 quinntaylor 43 
  <li>Easy-to-use interface</li>
539 tarmes 44 
  <li>Highly customisable templating system</li>
1103 quinntaylor 45 
  <li>Colourisation of file listings; MIME type support</li>
46 
  <li>Blame (annotation) view of file authorship</li>
47 
  <li>Comparing revisions of files / directories</li>
48 
  <li>Revision and log message browsing / searching</li>
49 
  <li>Download of files and folders</li>
539 tarmes 50 
  <li>Apache MultiViews support</li>
1103 quinntaylor 51 
  <li>RSS feed support for monitoring any resource</li>
900 quinntaylor 52 
  <li>Support for <code>bugtraq:*</code> SVN properties</li>
1103 quinntaylor 53 
  <li>Supports multiple repositories, local or remote</li>
54 
  <li>Optional path-based restriction of privileges</li>
55 
  <li>Multiple languages and on-demand switching</li>
539 tarmes 56 
</ul>
57 
 
58 
<p>Since it's written using PHP, WebSVN is also very portable and easy to install.</p>
59 
 
60 
<h2><a name="installation"></a>Installation</h2>
61 
 
1103 quinntaylor 62 
<p>Grab the source and stick it somewhere that your server can get to. You need to have <strong>PHP 4.3.0</strong> or greater installed and working. Additionally you need <strong>SVN 1.2.0</strong> or greater. Also note that WebSVN won't currently work in safe mode, due to the need to call the <code>svn</code> and <code>svnlook</code> commands. No other external programs are required.</p>
539 tarmes 63 
 
1103 quinntaylor 64 
<p>If it isn't already, make sure the cache directory has permissions of at least 0700 and is owned by the process your webserver is running under. This is used to cache RSS files. It is not recommended to set the directory to full write, 0777.</p>
539 tarmes 65 
 
1103 quinntaylor 66 
<p>Make a copy of <code>include/distconfig.php</code> and name it <code>include/config.php</code>, then edit it as directed in the file itself. Even with only the default config file, pointing your browser at the index.php file should display a WebSVN page that instructs you to set up one or more repositories.</p>
539 tarmes 67 
 
730 dirkthomas 68 
<!--
69 
<p>You'll also need diff (preferably the GNU version; for Windows users I'd
70 
recommend the Cygwin version) and svnlook available.</p>
71 
 
539 tarmes 72 
<p><b>Windows users:</b> Note that some of the features offered by WebSVN, when
73 
enabled, require the use of various external programs. They can be downloaded
74 
from these locations:</p>
75 
 
730 dirkthomas 76 
<p>Diff/Sed/Gzip/Tar: <a href="http://www.cygwin.com/">http://www.cygwin.com/</a></p>
77 
-->
539 tarmes 78 
 
1103 quinntaylor 79 
<h2><a name="addingrepos"></a>Adding Repositories</h2>
539 tarmes 80 
 
1103 quinntaylor 81 
<p>Repositories to be browsed must be specified in <code>include/config.php</code> so WebSVN knows how to access them. The two simplest ways to specify repositories are to use:</p>
539 tarmes 82 
 
1103 quinntaylor 83 
<ul>
84 
  <li><code>$config->addRepository(...)</code> to add repositories one-by-one, or</li>
85 
  <li><code>$config->parentPath(...)</code> to add a directory full of repositories at once.</li>
86 
</ul>
87 
 
88 
<h3><a name="credentials"></a>Credentials</h3>
89 
 
90 
<p>If WebSVN must supply a username and password to access a remote repository, you can supply these arguments in the <code>$config->addRepository(...)</code> call for that repository &mdash; consult <code>include/distconfig.php</code> for specifics. If the credentials are sensitive, be sure to set the read permissions for the config file appropriately.</p>
91 
 
92 
<h3><a name="groups"></a>Groups</h3>
93 
 
94 
<p>WebSVN allows you to group repositories logically if desired &mdash; <code>include/distconfig.php</code> documents how to associate repositories and parent paths with groups in detail. When groups exist, using <code>$config->useTreeIndex()</code> will create a hierarchical index page with collapsible/expandable group sections.</p>
95 
 
96 
<h3><a name="svnclienturls"></a>SVN Client URLs</h3>
97 
 
98 
<p>If you want to provide the URL that SVN clients should use to access a  repository (whether local or remote), you can provide it for a single repository or a parent path &mdash; consult <code>include/distconfig.php</code> for specifics. The SVN client link should be to the root path of a repository; path elements will be appended to it as needed. To see this in action, browse <a href="http://demo.websvn.info/listing.php?">demo.websvn.info</a> and look for the SVN links.</p>
99 
 
100 
<h2><a name="templates"></a>Templates</h2>
101 
 
102 
<p>WebSVN is able to customize its appearance through the use of a templating system, and includes several built-in templates. The template paths users can choose from may be specified in <code>include/config.php</code> using <code>$config->addTemplatePath(...)</code> etc.</p>
103 
 
104 
<p>Those who wish to customise the look and feel a little should read <a href="templates.html">templates.html</a>, which explains the highly configurable template system.</p>
105 
 
539 tarmes 106 
<h2><a name="colourisation"></a>Colourisation</h2>
107 
 
900 quinntaylor 108 
<p><a href="http://qbnz.com/highlighter/">GeSHi</a> (Generic Syntax Highlighter)  is bundled with WebSVN. To use it, just make sure config.php has this line uncommented:</p>
539 tarmes 109 
 
900 quinntaylor 110 
<pre>
111 
$config->useGeshi();
112 
</pre>
684 dirkthomas 113 
 
900 quinntaylor 114 
<p>Alternatively, you can use <a href="http://www.gnu.org/software/enscript/">Enscript</a> 1.6 or higher to view files with syntax colouring. (You'll also need <a href="http://ftp.gnu.org/gnu/sed/">sed</a>.) To use Enscript, simply set the paths in the config file, comment out the GeSHi line above, and then uncomment this line:</p>
730 dirkthomas 115 
 
900 quinntaylor 116 
<pre>
539 tarmes 117 
$config->useEnscript();
118 
</pre>
119 
 
120 
<h2><a name="multiviews"></a>Multiviews</h2>
121 
 
1103 quinntaylor 122 
<p>You may choose to configure access to your repository via Apache's MultiView system. This will enable you to access a repository using a url such as:</p>
539 tarmes 123 
 
900 quinntaylor 124 
<pre>http://example.com/wsvn/repname/path/in/repository</pre>
539 tarmes 125 
 
126 
<p>To do this you must:</p>
127 
 
128 
<ul>
900 quinntaylor 129 
  <li>Place wsvn.php where you want to. Normally you place it such that it's accessible straight after the servername, as shown above.</li>
130 
  <li>Configure the parent directory of wsvn.php to use MultiViews (see Apache docs)</li>
131 
  <li>Change config.php to include the line <code>$config->useMultiViews();</code></li>
132 
  <li>Change the path configured at the beginning of the wsvn.php script</li>
539 tarmes 133 
</ul>
134 
 
900 quinntaylor 135 
<p>Now go to <code>http://example.com/wsvn/</code> and make sure that you get the index page.</p>
539 tarmes 136 
 
542 tarmes 137 
<p>The repname part of the URL is the name given to it in the config.php file.
539 tarmes 138 
For this reason you may wish to avoid putting spaces in the name.</p>
139 
 
900 quinntaylor 140 
<h3><a name="multiviewsexample"></a>Multiviews example</h3>
539 tarmes 141 
 
1157 quinntaylor 142 
<p>First, Apache needs to know that you want to enable MultiViews for the root directory. You may need to enable the MultiViews option in the Apache configuration, as explained in <a href="http://httpd.apache.org/docs/2.2/content-negotiation.html#multiviews">these Apache docs</a>. For example, if my Apache directory root were set <code>/var/apache/htdocs</code>, the corresponding block in Apache might look something like this:</p>
539 tarmes 143 
 
900 quinntaylor 144 
<pre>
1157 quinntaylor 145 
&lt;Directory "/var/apache/htdocs"&gt;
146 
    Options Indexes FollowSymLinks MultiViews
147 
    AllowOverride None
148 
    Order allow,deny
149 
    Allow from all
150 
&lt;/Directory&gt;
539 tarmes 151 
</pre>
152 
 
1157 quinntaylor 153 
<p>Alternatively, you can include the following line in the directory's <code>.htaccess</code> file, assuming that the appropriate AllowOverrides directive is set up.</p>
539 tarmes 154 
 
900 quinntaylor 155 
<pre>
1157 quinntaylor 156 
Options MultiViews
539 tarmes 157 
</pre>
158 
 
1157 quinntaylor 159 
<p>Let's suppose that WebSVN is installed in a directory called <code>websvn</code> within the Apache document root directory. Normally, WebSVN would be accessed at <code>http://example.com/websvn/</code>. With MultiViews enabled, the base path for all WebSVN pages would be <code>http://example.com/websvn/wsvn/</code>. (If you would prefer <code>http://example.com/wsvn/</code> instead, move/copy wsvn.php from the WebSVN installation to the document root directory.) You may need to modify the <code>$locwebsvnhttp</code> variable at the beginning of wsvn.pnp to match your directory location.</p>
539 tarmes 160 
 
1157 quinntaylor 161 
<p>You must also enable Multiviews in the WebSVN <code>include/config.php</code> file by adding this line:</p>
162 
 
900 quinntaylor 163 
<pre>
539 tarmes 164 
$config->useMultiViews();
165 
</pre>
166 
 
1157 quinntaylor 167 
<p>If all has gone well, repositories should now by accessible at <code>http://example.com/wsvn/</code>.</p>
539 tarmes 168 
 
1157 quinntaylor 169 
<p>Note the index page can be accessed through <code>http://example.com/wsvn/</code>. If you want to view the index page at <code>http://example.com/</code>, you need to add another directive to the .htaccess file:</p>
539 tarmes 170 
 
900 quinntaylor 171 
<pre>
539 tarmes 172 
DirectoryIndex wsvn.php
173 
</pre>
174 
 
175 
<h2><a name="authentication"></a>Access rights and authentication</h2>
176 
 
900 quinntaylor 177 
<p>You may wish to provide an authentication mechanism for WebSVN. One obvious solution is to protect the entire WebSVN directory with some form of Apache authentication mechanism, but that doesn't allow for per repository authentication.</p>
539 tarmes 178 
 
900 quinntaylor 179 
<p>WebSVN provides and access rights mechanism that uses your SVN access file to control read access to the repository. This means that you only have to maintain one file to define both Subversion and WebSVN access rights.</p>
539 tarmes 180 
 
900 quinntaylor 181 
<p>For this to work, you need to configure your authentication method to the <code>/websvn/</code> (or <code>/wsvn/</code>) directory. This should be the same authentication as you use for the svn repositories themselves. Here's an example using SSPI:</p>
539 tarmes 182 
 
900 quinntaylor 183 
<pre>
184 
&lt;Location /websvn/&gt;
539 tarmes 185 
  AuthType SSPI
186 
  SSPIAuth On
187 
  SSPIAuthoritative On
188 
  SSPIDomain IMAJEMAIL
189 
  SSPIOfferBasic On
190 
  Require valid-user
900 quinntaylor 191 
&lt;/Location&gt;
539 tarmes 192 
</pre>
193 
 
900 quinntaylor 194 
<p>Note the use of the trailing <code>/</code> in the Location directive. If you use <code>&lt;Location /websvn&gt;</code>, you won't be able to access the index.</p>
539 tarmes 195 
 
900 quinntaylor 196 
<p>You should change <code>/websvn/</code> to <code>/wsvn/</code> if you're using multiviews.</p>
539 tarmes 197 
 
900 quinntaylor 198 
<p>Also note that you should not use the <code>AuthzSVNAccessFile</code> command to define the access file.</p>
539 tarmes 199 
 
900 quinntaylor 200 
<p>Now that you've defined your authentication, you'll be asked for your user name and password in order to access the WebSVN directory. All that's left is to configure WebSVN to use your Subversion access file to control access. Add this line to your config.php file:</p>
539 tarmes 201 
 
900 quinntaylor 202 
<pre>
203 
$config->useAuthenticationFile('/path/to/accessfile');
539 tarmes 204 
</pre>
205 
 
900 quinntaylor 206 
<p>Note that if your access file gives read access to, for example, path <code>/a/b/c/</code> but not to <code>/a/b/</code>, then the user will be given restricted access to <code>/a/b/</code> in order to reach <code>/a/b/c/</code>. The user will not be able to see any other files or directories in <code>/a</code> or <code>/a/b/</code>.</p>
539 tarmes 207 
 
208 
<p>You should read the <a href="http://svnbook.red-bean.com/">Subversion book</a> for information on the access file format.</p>
209 
 
210 
<h2><a name="problems"></a>Common problems</h2>
211 
 
1103 quinntaylor 212 
<dl>
213 
  <dt>Accented Characters</dt>
214 
  <dd>WebSVN is designed to worked with accented characters. To do this, it uses either the multibyte string funtions or the iconv function. This may not be installed on your system. If you aren't getting the characters that you expect, make sure that the multibyte string or iconv extension is being loaded in php.ini. Windows users will need to copy the appropriate DLLs of iconv to the system directory (from the PHP installation directory).</dd>
215 
  <dt>Executing a Windows shell</dt>
216 
  <dd>On a Windows machine, this error is reported: <code>Warning: shell_exec(): Unable to execute</code>. If you experience this problem, you need to give <code>IUSR_&lt;machinename&gt;</code> execute permissions on <code>&lt;systemroot&gt;\system32\cmd.exe</code>. Under most systems, the file will be <code>C:\WINDOWS\system32\cmd.exe</code>. Right-click on the file, choose properties, and on the security tab click the "Add" button. Add the <code>IUSR_&lt;machinename&gt;</code> user, and then select the "read" and "read &amp; execute" boxes.</dd>
217 
</dl>
539 tarmes 218 
 
219 
<h2><a name="license"></a>License</h2>
220 
 
900 quinntaylor 221 
<p><a href="http://www.fsf.org/licensing/licenses/gpl.html">GNU Public licence</a></p>
539 tarmes 222 
 
624 spetters 223 
</div>
224 
 
539 tarmes 225 
</body>
226 
</html>