Installing Insurrection on Debian

Insurrection is a very powerfull and nice-looking webgui for the version control system Subversion. It uses modern techniques to make browsing Repositories easy and intuitive.

Prerequirements

There are mainly two parts you need for insurrection, that would be all the necessary software, and a DNS.

Software

The Insurrection scripts are written in Perl. So you need the Perl interpreter, which is usually already installed on a Debian system. You also need Apache with the modules dav,svn,proxy and rewrite. And of course you need subversion. It's easy to install all those packages via apt as root:

$> apt-get install perl apache2 subversion libapache2-svn

DNS

You will also need a DNS Server which you can configure. Insurrection only works if it's access by a domain name, therefore you have to set up a DNS Server to point the desired domain name to a apache server. In this howto I will not explain how to do this, but you can find a lot about it on the Internet.

Authentication and repository folder

Folders and files

Now we need two folders. One for all the repositories and the other for the authentication files. In this howto I will use /srv/svn/auth as authentication folder and /srv/svn/repos for the repositories. If you want to use different directories feel free to use them but rembember to use them all throughout instead of mine. So now we create them:

$> mkdir /srv/svn $> mkdir /srv/svn/auth $> mkdir /srv/svn/repos

Later the apache process will have to read and write in those directories, so we let the user und group of apache own the directories. Usually the user and the group are called www-data but you might want to check that in your apache configuration. On the commandline you can easilly change the ownership by the following commands:

$> cd /srv $> chown -R www-data svn $> chgrp -R www-data svn

In the authentication folder we create two files: The Apache authentication file (passwords) and the access configuration file (access) of Subversion (which Insurrection uses too).

$> cd /srv/svn/auth $> touch passwords access

Authentication - file "passwords"

The Apache authentication file can be modified with htpasswd. Basically you give the filename and username as a parameter and are then asked for the users password. That way you can add users or change their passwords.

$> htpasswd passwords user Password:

For more information on htpasswd consult http://httpd.apache.org/docs/2.0/programs/htpasswd.html.

Access control - file "access"

How this configuration files works is described very well in the Subversion Book: http://svnbook.red-bean.com/en/1.4/svn.serverconfig.pathbasedauthz.html

Notice: If you want anonymous access you have to define this for every repository in this file.

Installing Insurrection

Now we have to get Insurrection. You can check it out from its subversion repository into the root or any subfolder of your web presence.
In this Howto we will create a new virtual server for insurrection, so it will be at the document root. But whenever you have to do something differently if insurrection is in a subfolder I will tell you.
We will use /var/www/insurrection as the document root of our new virtual server, but perhaps you want to place it somewhere else. Just remember to use your path instead of this one, whenever it occures.

$> svn co http://svn.code-host.net/svn/Insurrection/trunk /var/www/insurrection

Cleanup

There might be several files and folders you don't need to run Insurrection. If you want you can delete them:
.htauth browser-tests rewrite-test screenshots .svn_index httpd.conf.patch insurrection.conf

Rights and Ownership

First you should change the owership of all files and folders to the apache user and group. As previously mentioned this is usually www-data but again you might want to check that in your apache configuration.

$> cd /var/www/insurrection $> chown -R www-data * $> chgrp -R www-data *

We also have to make sure that all scripts are executable. So we have to set the executable flag for the files by running the following command in the insurrection folder:

$> chmod u+x *.pl *.cgi

Insurrection configuration files

Insurrection uses several programming languages, therefore we have several configuration files to adjust to our needs.

insurrection.pl

Altough this configuration file is selfexplaining some remarks on the settings follow:

$SVN_INDEX_TITLE: This is the title of the main page, usually shown in the browser's window title. Should be a string which identifies your repositories.
$SVN_BASE: All repositories will lie under this directory. It should be our previously created /srv/svn/repos or whatever you named it.
$SVN_AUTH: The other previously created directory for authentication files, /srv/svn/auth or the direcotry you created for this.
$SVN_LOGS: The Logfiles will lie under this direcotry, on debian usually /var/log/apache2
$SVN_BIN: The directory in which the subversion binaries lie. If you did a normal installation this would be /usr/bin
$EMAIL_DOMAIN: The domain of your email adress with a prefixed @. This will be used in the rss part for naming the author and for welcome mails to new users.
$HTTPS_LOGIN: Set to 1 if you want authentication to be done only through HTTPS, otherwise 0. Of course https has to be configured in apache for this to work.
$SVN_LOG_ENTRIES: The amount of revisions usually shown.
$SVN_URL_PATH: Under which path Insurrection lies in your web-hierarchy. For example:
If Insurrection will be reached through http://server/insurrection then this value has to be set to /insurrection/ (notice the leading and trailing slashes).
If Insurrection lies in the document root (http://server/ will lead to Insurrection) you have to set this to just one slash (/),
which is the case in this Howto.
$SVN_REPOSITORIES_URL: This variable represents the subdirectory under which all repositories will be reached. For example http://server/ will lead to Insurrection whereas all repositories URLs will begin with http://server/svn/

You don't have to change the last three variables if your subversion binaries aren't namend differently to the standard.

insurrection.js

The only thing you have to really do here is checking that Insurrection.SVN_URL is set to the same as $SVN_REPOSITORIES_URL of the Insurrection.pl file.
The other variable, Insurrection.SliderSteps, sets how many steps the unfolding of popups will use. A higher number means slower, a lower numbers means faster. 1 means instantly.

insurrection.xsl

If Insurrection is installed in a subfolder you have to adjust the paths to all files in this XML Style Sheet. Those paths have to be absolute and not relative. At the time of writing the changes would have to be made to the following lines:
(Replace "subfolder" with the name of your actual subfolder.)

Line 31: <img src="/subfolder/Logo.gif" ... Line 41: <link href="/subfolder/favicon.ico" ... Line 42: <link href="/subfolder/styles.css" ... Line 43: <script src="/subfolder/insurrection.js" ... Line 44: <script src="/subfolder/svnindex.js" ... Line 45: <script src="/subfolder/log.js" ...

And the same from Line 52 to 73 with the paths to the images

<xsl:template name="closedicon-path">/subfolder/closed.gif</xsl:template>
etc...

.htaccess

We can split this configuration up in two parts. At the beginning of the file the authentication stuff and at the end all the rewrite stuff.

AuthUserFile should point to the password file we previously created with htpasswd2,which would be /srv/svn/auth/passwords.
AuthName is the authentication realm. Basically this will be shown to the user if he has to authenticate.
AuthType should be left to Basic, except you know why you want another authentication type (which will probably not work on some browsers but most certanly be more secure).

Futher down at the rewrite rules we have to change some lines:

80: RewriteCond /home/subversion/www/%{HTTP_HOST}.gif !-f

There we have to give the full path to Insurrection. For example if Insurrection is at /var/www/insurrection this has to be:

80: RewriteCond /var/www/insurrection/%{HTTP_HOST}.gif !-f

(For further explanation of this part see the chapter Domainname.)

If you have set Insurrection to be under a folder (and not at the root) of your web presence you have to change the last 4 RewriteRules (first is at line 130). Change http://%{HTTP_HOST}/ to have the directory included. For example: http://%{HTTP_HOST}/subfolder/, replacing "subfolder" with the name of your acutal subfolder.

Domainname

Insurrection only works if you connect to the server by a domainname and not by IP.

Insurrection checks whether there is a gif image named [your full hostname].gif in the insurrection folder. This gif image is also used as the logo shown at the Insurrection main page. So you have to create a little gif file with a nice logo and put it in the insurrection main folder. Say your server is at svn.mycompany.com you have to name the file svn.mycomany.com.gif.

If someone tries to access the insurrection page by IP or another domain name he will get the error message "Forbidden".

Apache configuration

The subversion webdav, rewrite and proxy modules have to be loaded. Modules are loaded by creating a symbolic link in /etc/apache2/mods-enabled to their correspoding .conf and .load file in /etc/apache2/mods-available. As this is already the case for subversion webdav module, we only have to add the other two modules:

$> cd /etc/apache2/mods-enabled $> ln -s ../mods-available/rewrite.load $> ln -s ../mods-available/proxy.conf $> ln -s ../mods-available/proxy.load

Next we create a virtual host for Insurrection. A virtual host allows you to...
Leave virtualHost out... can put everything in server config.. or use _default_ as domain name.
The configuration files for virtual hosts are at /etc/apache2/sites-available/. So we put a new file called insurrection there. In this file we write the following configuration, in which I explain the most important lines:

# use the domainname you configured in your DNS server, or _default_ <VirtualHost svn.mycompany.com:80> ServerName svn.mycomapny.com # create own logfiles for subversion (and Insurrection) CustomLog /var/log/apache2/svn_error_log common ErrorLog /var/log/apache2/svn_error_log # # The Insurrection tree lives here... # DocumentRoot /var/www/insurrection <Directory "/var/www/insurrection"> Options FollowSymLinks ExecCGI # # AllowOverride controls what directives may be placed in .htaccess files. # It can be "All", "None", or any combination of the keywords: # Options FileInfo AuthConfig Limit # # This is needed because we do many things with the .htaccess file. AllowOverride All Order allow,deny Allow from all </Directory> # Never show our internal .svn directories <DirectoryMatch "^/.*/\.svn"> Order allow,deny Deny from all </DirectoryMatch> <Location /svn> DAV svn # this is the root under which all our repositories lie SVNParentPath /srv/svn/repos SVNIndexXSLT "/insurrection.xsl" # If insurrection is in a subfolder you should use the next line instead # but remember to replace "subfolder&qout; with the name of your actual subfolder # SVNIndexXSLT "/subfolder/insurrection.xsl" # our access control policy AuthzSVNAccessFile /srv/svn/auth/access # try anonymous but require a user if needed Satisfy Any Require valid-user # how to authenticate a user AuthType Basic AuthName "Code-Host Repository" # our previously created file containing all usernames and passwords AuthUserFile /srv/svn/auth/passwords </Location> </VirtualHost>

Now we enable this configuration by linking to it from the /etc/apache2/sites-enabled folder:

$> cd /etc/apache2/sites-enabled $> ln -s ../sites-available/insurrection

Startup

To see Insurrection in action we should create a repository now:

$> svnadmin create /srv/svn/repos/myFirstRepository

After restarting Apache now Insurrection should be up and running, so let's give it a try:

$> /etc/init.d/apache2 restart

Go with your browser to your previously configured virtual host (http://svn.mycompany.com) and see if Insurrection is there.

Known Problems

At the moment there is only one known problem:

"can't set pointer (...) invalid argument"

This error usually appears if mod_dav_svn is not linked against the same version of APR as Apache.

written by Severin Leonhardt