WebSVN Installation Guide

Why WebSVN?

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.

WebSVN offers the following key features:

• Easy-to-use interface
• Highly customisable templating system
• Colourisation of file listings; MIME type support
• Blame (annotation) view of file authorship
• Comparing revisions of files / directories
• Revision and log message browsing / searching
• Download of files and folders
• Apache MultiViews support
• RSS feed support for monitoring any resource
• Support for bugtraq:* SVN properties
• Supports multiple repositories, local or remote
• Optional path-based restriction of privileges
• Multiple languages and on-demand switching

Since it's written using PHP, WebSVN is also very portable and easy to install.

Installation

Sources and dependencies

Grab the source and stick it somewhere that your server can get to. You need to have PHP 5.6 or greater installed and working. Additionally you need SVN 1.7 or greater. Also note that WebSVN won't currently work in safe mode, due to the need to call the svn and svnlook commands. While no other external programs are required, you need to provide additional PHP libraries if not already installed. It's recommended to use the package manager of your operating system for each individual library or, if it doesn't provide those, that of PHP itself called PEAR. At least PEAR should most likely be available using your package manager. With e.g., a Debian based operating system simply issue the following commands to install the dependencies using PEAR:

1. apt-get install php-pear
2. pear channel-discover pear.geshi.org
3. pear install Archive_Tar
4. pear install geshi/geshi
5. pear install Text_Diff

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.

Configuration

WebSVN always requires a special configuration file, for which a template is provided as include/distconfig.php. Only the things mentioned in that template are valid configs at all and some of those are even necessary, e.g., WebSVN obviously needs to know which SVN repos it should publish. Making the necessary config file available to WebSVN can be done using two ways: Either simply by copying the template file to the hard-coded path include/config.php and/or by setting the environment variable WEBSVN_PATH_CONF in a way so that PHP can read its value. That value is expected to be the path to the config file to use and things like symlinks work as well of course, as long as those are handled transparently by the file system.

Using the environment variable has two main benefits: One doesn't neet to store additional files in the deployment of WebSVN and the path given by WEBSVN_PATH_CONF is used additionally to include/config.php, if that file is present at all. If not, the file given by the environment variable is used exclusively. This approach allows to override specially chosen configs of some main configuration file using another one based on things like the current location of a request to WebSVN. A webserver like Apache HTTPd could be configured using Location blocks to provide different paths to config files using the environment variable like in the following example:

<Location "/websvn/[...]">
	SetEnv WEBSVN_PATH_CONF "/home/websvn/config/[...]/config.php"
</Location>

Considering both the hard-coded config file path and the more dynamic environment variable allows setups in which one installation of WebSVN hosts various SVN repos configured using $config->parentPath(...). That statement would simply be added the those files only provided by the environment variable and depending on the location of some request. All other common things like available templates, syntax highlighting, etc. would be set in include/config.php. That allows structuring SVN repos using subdirs like is supported by svnserve, which is otherwise not supported by WebSVN. The latter checks if each directory is an SVN repo already or simply ignores it. The following is a more comprehensive example:

• /home/svn_repos/ParentDir1
  • Repo1
  • Repo2
  • ParentDir2
    • Repo3
    • Repo4
• /home/svn_repos/ParentDir3
  • Repo5
  • Repo6

<Location "/websvn/ParentDir1">
	SetEnv WEBSVN_PATH_CONF "/home/websvn/config/ParentDir1/config.php"
</Location>

<Location "/websvn/ParentDir1/ParentDir2">
	SetEnv WEBSVN_PATH_CONF "/home/websvn/config/ParentDir1/ParentDir2/config.php"
</Location>

<Location "/websvn/ParentDir3">
	SetEnv WEBSVN_PATH_CONF "/home/websvn/config/ParentDir3/config.php"
</Location>

/home/websvn/config/ParentDir1/config.php:

<?php
$config->parentPath("/home/svn_repos/ParentDir1");
?>

/home/websvn/config/ParentDir1/ParentDir2/config.php:

<?php
$config->parentPath("/home/svn_repos/ParentDir1/ParentDir2");
?>

/home/websvn/config/ParentDir3/config.php:

<?php
$config->parentPath("/home/svn_repos/ParentDir3");
?>

In such a setup, the directory /home/websvn/config/ could be a SVN working copy containing the default config under /home/websvn/config/config.php, being symlinked into the formerly mentioned target in the installation directory of WebSVN. This allows all configs to be managed at the same place and optionally versioned as well.

Adding Repositories

Repositories to be browsed must be specified in include/config.php so WebSVN knows how to access them. The two simplest ways to specify repositories are to use:

• $config->addRepository(...) to add repositories one-by-one, or
• $config->parentPath(...) to add a directory full of repositories at once.

Credentials

If WebSVN must supply a username and password to access a remote repository, you can supply these arguments in the $config->addRepository(...) call for that repository — consult include/distconfig.php for specifics. If the credentials are sensitive, be sure to set the read permissions for the config file appropriately.

Groups

WebSVN allows you to group repositories logically if desired — include/distconfig.php documents how to associate repositories and parent paths with groups in detail. When groups exist, using $config->useTreeIndex() will create a hierarchical index page with collapsible/expandable group sections.

SVN Client URLs

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 — consult include/distconfig.php for specifics. The SVN client link should be to the root path of a repository; path elements will be appended to it as needed.

Templates

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 include/config.php using $config->addTemplatePath(...) etc.

Those who wish to customise the look and feel a little should read templates.html, which explains the highly configurable template system.

Colourisation

GeSHi (Generic Syntax Highlighter) is bundled with WebSVN. To use it, just make sure config.php has this line uncommented:

$config->useGeshi();

Alternatively, you can use Enscript 1.6 or higher to view files with syntax colouring. (You'll also need sed.) To use Enscript, simply set the paths in the config file, comment out the GeSHi line above, and then uncomment this line:

$config->useEnscript();

Multiviews

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:

http://example.com/browse/repname/path/in/repository

To do this you must:

• Place browse.php where you want to. Normally you place it such that it's accessible straight after the servername, as shown above.
• Configure the parent directory of browse.php to use MultiViews (see Apache docs)
• Change config.php to include the line $config->useMultiViews();
• Change the path configured at the beginning of the browse.php script

Now go to http://example.com/browse/ and make sure that you get the index page.

The repname part of the URL is the name given to it in the config.php file. For this reason you may wish to avoid putting spaces in the name.

Multiviews example

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 these Apache docs. For example, if my Apache directory root were set /var/apache/htdocs, the corresponding block in Apache might look something like this:

<Directory "/var/apache/htdocs">
	Options Indexes FollowSymLinks MultiViews
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

Alternatively, you can include the following line in the directory's .htaccess file, assuming that the appropriate AllowOverrides directive is set up.

Options MultiViews

Let's suppose that WebSVN is installed in a directory called websvn within the Apache document root directory. Normally, WebSVN would be accessed at http://example.com/websvn/. With MultiViews enabled, the base path for all WebSVN pages would be http://example.com/websvn/browse/. (If you would prefer http://example.com/browse/ instead, move/copy browse.php from the WebSVN installation to the document root directory.) You may need to modify the $locwebsvnhttp variable at the beginning of browse.php to match your directory location.

You must also enable Multiviews in the WebSVN include/config.php file by adding this line:

$config->useMultiViews();

If all has gone well, repositories should now by accessible at http://example.com/browse/.

Note the index page can be accessed through http://example.com/browse/. If you want to view the index page at http://example.com/, you need to add another directive to the .htaccess file:

DirectoryIndex browse.php

Access rights and authentication

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.

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.

For this to work, you need to configure your authentication method to the /websvn/ (or /wsvn/) directory. This should be the same authentication as you use for the svn repositories themselves.

Note the use of the trailing / in the Location directive. If you use <Location /websvn>, you won't be able to access the index.

You should change /websvn/ to /browse/ if you're using multiviews.

Also note that you should not use the AuthzSVNAccessFile command to define the access file.

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:

$config->useAccessFile('/path/to/accessfile');

Note that if your access file gives read access to, for example, path /a/b/c/ but not to /a/b/, then the user will be given restricted access to /a/b/ in order to reach /a/b/c/. The user will not be able to see any other files or directories in /a or /a/b/.

You should read the Subversion book for information on the access file format.

Common problems

Accented Characters

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).

Executing a Windows shell

On a Windows machine, this error is reported: Warning: shell_exec(): Unable to execute. If you experience this problem, you need to give IUSR_<machinename> execute permissions on <systemroot>\system32\cmd.exe. Under most systems, the file will be C:\WINDOWS\system32\cmd.exe. Right-click on the file, choose properties, and on the security tab click the "Add" button. Add the IUSR_<machinename> user, and then select the "read" and "read & execute" boxes.

License

GNU Public licence