XMLTagsEditHistoryDiscussion

  1. Introduction
  2. Installing Svnwiki
    1. Install Chicken Scheme
    2. Install Subversion
    3. Install SQLite
    4. Install Hyper Estraier (optional)
    5. Configure Apache Modules
    6. Download and install Chicken Extensions
    7. Download Svnwiki
    8. Prepare Svnwiki for compilation
    9. Compile Svnwiki
  3. Create a wiki
    1. Directories, files and Constants
    2. Create a Subversion repository
    3. Create your users' file
    4. Configure mod_dav_svn
    5. Checkout a copy of your repository
    6. Configure Svnwiki
    7. Set the post-commit hook script
    8. Install svnwiki extensions
    9. Initialize your repository
    10. Setup the stats script
    11. Prepare Apache to serve your wiki
      1. Content Negotiation
      2. Set svnwiki as your error document
  4. A note about versions and upgrading

Edit Link Top

Introduction

These guide explains how to install svnwiki and configure a wiki with it.

Edit Link Top

Installing Svnwiki

Edit Link Top

Install Chicken Scheme

You will need to install Chicken Scheme in the machine where you plan to build and run Svnwiki.

Some of the eggs that Svnwiki depends on require Chicken 2.6 or later.

You can download the latest release from http://www.call-with-current-continuation.org. Chicken respects the GNU standards for software distribution, so ./configure && make && make install should be enough to build it.

Your Chicken installation must have support for:

Edit Link Top

Install Subversion

As Svnwiki depends on Subversion, you will need to have it installed in the machine you plan to run it on. Svnwiki uses a Chicken extension that is linked against the libsvn_client library.

Note that you will require the C header files for Subversion. This means that even if you have Subversion installed, you *might* have to install an additional package:

Once you've built Svnwiki, you can uninstall all the development packages.

Edit Link Top

Install SQLite

You'll need to install the SQLite package and its development files (C header files).

Since Chicken 2.41 can't run svnwiki and the sqlite3 Chicken egg doesn't build with Chicken 2.3, you'll need to use a version of SQLite older than 3.

This is usually bundled in distributions. As with Subversion, you can uninstall the development package after you've built Svnwiki (in particular, after you've built Chicken's sqlite egg).

Edit Link Top

Install Hyper Estraier (optional)

If you want to make it possible for your users to search your wiki, install Hyper Estraier. This step is optional but highly recommended.

Edit Link Top

Configure Apache Modules

You will need to enable Apache's mod_dav and mod_dav_svn modules. The first is usually distributed as part of Apache. The later is usually bundled in a separate package:

Make sure the modules mod_dav and mod_dav_svn are enabled in Apache's configuration:

In FreeBSD, you will need something like this on httpd.conf:

LoadModule dav_module         libexec/apache2/mod_dav.so
LoadModule dav_svn_module     libexec/apache2/mod_dav_svn.so

In the case of Debian, you'll need links to /etc/apache2/mods-available/dav.load and /etc/apache2/mods-available/dav_svn.load in /etc/apache2/mods-enabled.

For SuSE, you'll need to mod_dav and mod_dav_svn included in the APACHE_MODULES directive in the /etc/sysconfig/apache2 file.

Edit Link Top

Download and install Chicken Extensions

Chicken has a framework for extending its functionality. These extensions are called «eggs», of which svnwiki uses a great number. The entire process of downloading and installing them can be performed by issuing the following command:

chicken-setup srfi-40 sandbox syntax-case sqlite3 stream-ext format-modular \
  content-type stream-cgi html-stream html-plots iconv stream-parser \
  stream-wiki scheme-dissect svn-client svn-post-commit-hooks orders \
  stream-httplog stream-sections url sha1 estraier gettext stream-base64

Note that the above command assumes:

You'll have to enter yes to download the eggs. Note that there are some dependencies among these eggs, so the order in which you install them is important.

To test that the eggs were successfully installed, you can run csi, the Chicken Scheme Interpreter, and, after evaluating the expression (use stream-wiki), make sure that (stream->string (wiki->html (string->stream "hey"))) evaluates to "<p>hey</p>". This test depends on several eggs (srfi-40, stream-ext, stream-wiki, stream-parser and html-stream) being correctly installed.

Edit Link Top

Download Svnwiki

You can download a release of Svnwiki from:

This will get you the stable version of svnwiki.

You can also download the latest source code directly from Svnwiki's Subversion repository. Use the following command:

svn checkout --username anonymous --password '' https://freaks-unidos.net/azul-home/src/svnwiki/trunk

Use the "anonymous" login, with the empty ("") password (both are already specified in the command line given).

Edit Link Top

Prepare Svnwiki for compilation

If you downloaded Svnwiki from its Subversion repository (as opposed to downloading one release), you'll need to prepare it for compilation. This is not necessary when you download a stable version. Make sure you have Autoconf and Automake installed and run:

aclocal && automake -a && autoconf

This should generate the files Makefile.in and configure.

Note that you will need a relatively recent version of both Autoconf and Automake, since the support for building programs from special programming languages (other than those Autoconf and Automake support natively) wasn't as good in previous releases. With old versions you will likely get a problem later when compiling (such as make telling you it doesn't know how to build certain files).

Edit Link Top

Compile Svnwiki

Svnwiki respects the GNU standards for software distribution, so ./configure && make && make install should be enough to build it. make will call chicken to compile the Scheme files into C files and then build them.

This will build two files:

Edit Link Top

Create a wiki

Edit Link Top

Directories, files and Constants

In order to create a wiki, you will need the following directories:

SVNPATH
This will hold your Subversion repositories (should you ever need more than one). You will only interact with subdirectories of it through svnadmin and Apache will also use it in order to serve your repository. You could use something like /usr/local/svn, /srv/svn or /home/aforero/repos here.
COPY
A path that you will use to initialize your wiki. You could use something as /tmp/svnwiki-repository. This directory does not need to exist.
STATIC-PATH
A directory inside your web tree to build static HTML files representing the pages in your wiki. Its associated URL where it can be consulted should be used as the value of STATIC-URL.
DATA-PATH
A directory that svnwiki-post-commit-hook can use to write data files.

You will need the following files:

HTPASSWDFILE
The path where you want the file with the passwords for accesing your Subversion repository to be created. You could use /etc/apache2/svn-htpasswd2. If this file exists, it should be an htpasswd file (if it doesn't it will be created below).

Constants:

NAME
The name of the wiki and its associated Subversion repository. You could use something like svnwiki.
URI
A string such as /svn that you'll use as the URI in URLs that access your Subversion repositories. For example, if you use /svn, the URLs for your repositories will look as http://localhost/svn/NAME.
REPOS-URL
The URL to the directory in your Subversion repository where your wiki contents are stored. Usually it will be your server's name, followed by /URI/NAME (eg. http://localhost/svn/svnwiki with the example values for NAME and URI). REPOS-URL will usually end with whatever you set BASE (see below) to.
USER and PASSWD
The login and password that Svnwiki will use to authenticate with the Subversion server.
STATIC-URL
The URL where the contents in STATIC-PATH can be consulted. svnwiki.cgi will redirect accesses to pages in the wiki to the files in STATIC-URL.
BASE
If your wiki contents are stored directly at the root of the Subversion repository, BASE should be set to the empty string (""). Otherwise, it should be set to the path inside the Subversion repository where the wiki contents will be stored. If BASE is not set to the empty string, you should make sure that REPOS-URL ends with the contents of BASE. For example, if your repository is http://localhost/svn/data and your wiki is stored in site/wiki, REPOS-URL should be set to http://localhost/svn/data/site/wiki and BASE to site/wiki.

The rest of the installation guide uses these values. You should replace occurences of their names with their values in the commands and configuration changes described in this file.

We advise you to make sure that:

If you are using revision r9601 or older (this is your case if you are using v0.1), you'll also need:

TMP-PATH
A local path where svnwiki.cgi will checkout its working copy of the repository. Use /tmp/svnwiki-rep-default or something like that (you'll need to make sure that the web user can write to its parent directory; if you don't understand what this means just use something under /tmp). Make sure this directory does not exist (you can erase it at anytime and svnwiki will simply recreate it whenever it needs it).
TMP-PATH-OTHER
The same semantics for TMP-PATH apply to this one, but you should use a different directory. It will be used by svnwiki-post-commit-hook to checkout a local copy of the repository. Again, this directory should not exist. The only difference between TMP-PATH and TMP-PATH-OTHER is that the former is used by svnwiki.cgi while the second by svnwiki-post-commit-hook.

Edit Link Top

Create a Subversion repository

Use the svnadmin tool to create your Subversion repository. You can do this as follows:

# mkdir -p SVNPATH/NAME
# svnadmin create SVNPATH/NAME

There's more information about svnadmin in the Version Control with Subversion book.

You'll also need to make this repository accessible (both readable and writable) by your web user (the user your web server runs as). To do this, set that user as the files' owner (the following command needs to be run as root):

# chown -R WWWUSER SVNPATH/NAME

Here PATH and NAME should be replaced as above and WWWUSER needs to be replaced with your web user. The web user defaults to the following values:

Edit Link Top

Create your users' file

You'll need to create a file with the list of users allowed to access your repository and their passwords. Use the htpasswd2 utility to create it:

# htpasswd2 -c HTPASSWDFILE USER

As you'll see, htpasswd2 will ask you to type the user's password. Enter PASSWD.

You'll only use the -c parameter the first time (to have htpasswd2 create the file). If you need to add more users to the file, don't include it.

The command is just htpasswd on Ubuntu Feisty.

Edit Link Top

Configure mod_dav_svn

At this point you'll need to setup a Location directive in your Apache configuration to make your Subversion repositories accessible through the DAV interface.

You could achieve this with the following directive:

<Location URI>
    DAV svn
    SVNParentPath SVNPATH

    # Anonymous first
    #   Remove the comments of the "Satisfy Any" line if you want
    #   to allow anyone to read and commit to your repository
    #   with no authentication.
    # Satisfy Any

    # authenticating the valid ones
    Require valid-user
    AuthType Basic
    AuthName "Subversion Authentication"
    AuthUserFile HTPASSWDFILE
</Location>

Once you've done this restart Apache and make sure you can get to your repository at http://localhost/repos/NAME/.

Edit Link Top

Checkout a copy of your repository

At this point you should be able to checkout a copy of the (currently empty) repository you'll use for your wiki. You can do this with the following command:

$ svn co http://localhost/svn/svnwiki COPY

You'll need this directory in the future.

Edit Link Top

Configure Svnwiki

Svnwiki requires the creation of an /etc/svnwiki/config.scm file with an entry (a Scheme-expresion) for each different repository/wiki that you want Svnwiki to handle.

If you are using Svnwiki revision 9601 or older (this is the case if you are using v0.1), the entries should have the following format:

(NAME REPOS-URL TMP-PATH USER PASSWD STATIC-URL DATA-PATH STATIC-PATH BASE)

If you are using a more recent revision, you should omit TMP-PATH:

(NAME REPOS-URL USER PASSWD STATIC-URL DATA-PATH STATIC-PATH BASE)

Sure, we can give you an example:

("default"
  "https://freaks-unidos.net/azul-home/doc/wiki"
  ; The following should be included for r9601 or older revisions:
  ; "/tmp/svnwiki-bogowiki-rep"
  "myuser"
  "thepasswd"
  "https://bogowiki.org/"
  "/home/azul/var/svnwiki/somewiki/"
  "/var/www/bogowiki.org/htdocs/"
  "")

Edit Link Top

Set the post-commit hook script

This is an optional, though recommended, step. It will cause a static viewable copy with the entire contents of your wiki to be created in a given directory, from which requests can be served. If you decide to skip this step, make sure to omit the STATIC-URL directive in your config.scm file (see the previous step) so files are viewable through svnwiki.cgi.

Create a file SVNPATH/NAME/hooks/post-commit. If you are using revision 9372 or older (this includes v0.1), it should contain the following:

#!/bin/bash
svnwiki-post-commit-hook REPOS-URL USER PASSWD BASE TMP-PATH-OTHER STATIC-PATH DATA-PATH &

If you are using version r9373 or more recent, it should contain:

#!/bin/bash
svnwiki-post-commit-hook NAME &

Make sure this file is runnable by any user (actually making sure your web user can run it will suffice).

# chmod a+x SVNPATH/NAME/hooks/post-commit

Furthermore, make sure svnwiki-post-commit-hook is in the PATH environment variable that Apache will pass to the Subversion post-commit script. If it isn't, you can always use the foll path to it in the script.

You'll need to make sure that WWWUSER can write to both STATIC-PATH and DATA-PATH, since that is the user that svnwiki-post-commit-hook will be run by. One way to do this is:

# chown -R WWWUSER STATIC-PATH DATA-PATH

Edit Link Top

Install svnwiki extensions

Optional functionality defining tags for your wiki is shipped as svnwiki extension files. The following is a list of some highly recommended extensions:

tags.scm
Defines basic tags: h1, ..., h6, big, small, center, pre
enscript.scm
Defines the enscript tag that you can use for syntax highlighting. If you install this extension, don't forget to install GNU enscript.
scheme.scm
Defines the scheme tag that you can use to embed Scheme code in your wiki pages. Embbeded code is executed in a restricted environment.
nowiki.scm
Defines the nowiki tag that you can use to prevent svnwiki from parsing certain portions of your document.
math.scm
Defines the math tag that you can use to include math in your documents. If you install this extension, you will also need the TexVC software.

To install these extensions download them as follows:

svn checkout https://anonymous:@galinha.ucpel.tche.br:8080/svn/chicken-eggs/stream-wiki/trunk/extensions/

Make a directory extensions inside DATA-PATH and move those extensions you want to enable to that directory. For example, to enable all of them, use:

mkdir DATA-PATH/extensions
mv extensions/*scm DATA-PATH/extensions

Edit Link Top

Initialize your repository

Svnwiki expects wiki repositories to contain a certain set of initial files. You can use our very own The Nameless Wiki as a base. By the way, any help improving The Nameless Wiki would be appreciated; it would probably help future Svnwiki users.

To do this use the prepare.sh script distributed as part of Svnwiki. You should pass it the path where you checked out a copy of your wiki's repository and the URL where your instance of the svnwiki.cgi application can be accessed:

$ ./prepare.sh COPY SVNWIKI-CGI-URL/NAME

It will download files directly from The Nameless Wiki's repository and add them to your local copy. If no errors take place, commit your copy:

$ svn commit COPY

To create your first file go to SVNWIKI-CGI-URL; if all went well, you should be able to edit the default file.

Edit Link Top

Setup the stats script

This steps is optional. If you don't do it, your visitors won't be able to see HTML files with the access statistics for the files in your wiki (example).

To generate files with stats use the svnwiki-stats program. It is run as follows:

$ svnwiki-stats URL USER PASSWORD PATH-IN WEB-PATH DATA-PATH ACCESS-LOG

Here ACCESS-LOG needs to be replaced with a path to a file in access-log format with the new hits that should be registered since the last time svnwiki-stats was run. svnwiki-stats will register all hits it finds in ACCESS-LOG. For that reason, it is important that you never feed it any hit multiple times.

One way to solve this is to call svnwiki-stats as part of the following script:

 #!/bin/sh
 # Arguments for svnwiki-stats:
 URL=""
 USER=""
 PASSWORD=""
 PATH_IN=""
 WEB_PATH=""
 DATA_PATH=""

 # Replace with the path to your (real, live) access log:
 ACCESS_LOG="/www/logs/access_log";

 # Replace with the path where you'll store old hits (that svnwiki-stats
 # already processed):
 ACCESS_LOG_STORE="/www/logs/access_log.real";

 # Path to Apache's PID file:
 PIDFILE="/var/run/httpd.pid";

 # Add new hits to $ACCESS_LOG.process and wipe clean $ACCESS_LOG:

 if test -a $ACCESS_LOG.process; then
   cat $ACCESS_LOG >> $ACCESS_LOG.process && rm $ACCESS_LOG;
 else
   mv $ACCESS_LOG $ACCESS_LOG.process;
 fi;
 kill -HUP $(cat $PIDFILE) &&

 # Parse new hits:
 svnwiki-stats $URL $USER $PASSWORD $PATH_IN $WEB_PATH $DATA_PATH $ACCESS_LOG.process

 cat $ACCESS_LOG.process >>$ACCESS_LOG_STORE
 rm $ACCESS_LOG.process

You will, of course, want to run this script periodically (to update the stats files). You'll probably want to use a cron job (and redirect its standard output and error output to /dev/null). It would be a good idea to run it once to make sure you got everything correctly set.

Note that the HTML files generated will use a 1x1 pixel file for the plots. The (absolute or relative) URL for this file should be specified as the value of the svnwiki:stats-file Subversion property in the root of your repository (you could override the value for specific files or directories by setting this property to a different value on them).

Edit Link Top

Prepare Apache to serve your wiki

You'll need to modify your Apache configuration to enable it to handle the directory with your static files (created by the svnwiki-post-commit-hook program) more intelligently.

Edit Link Top

Content Negotiation

Turn on the MultiViews option for the <Location> or <Directory> entry in your Apache configuration for the directory with the static (web-accessable) files for your wiki. This will enable content negotiation, which makes it so people requesting foo may get sent foo.html or foo.pdf (which, in turn, makes it possible to make links in the wiki without having to enter the file extension).

If no <Location> nor <Directory> entry exists for your wiki, you will need to create it, probably inside the <VirtualHost> declaration for the host that will be serving your wiki.

<Directory "PATH_OUT">
  Options MultiViews
</Directory>

Edit Link Top

Set svnwiki as your error document

You will need to set an error document handler for 404 errors in your wiki. What this does is make it so whenever someone accesses an unexisting page in your wiki, rather than get a 404 Not Found error telling her the page requested does not exist, Apache runs the svnwiki CGI program, which presents the HTML form she can use to create it.

In your Apache configuration, in the Directory or VirtualHost entry for your STATIC-PATH, add the following entry. The URI portion before the question mark should point to your svnwiki CGI application.

ErrorDocument 404 /cgi-bin/svnwiki?WIKI-NAME

Make sure that this directive won't be applied to REPOS-URL. If it is, you'll get errors whenever you try to commit to your repository.

Edit Link Top

A note about versions and upgrading

We are working hard to simplify the procedures outlined in this guide by automating as much as possible.

One unfortunate consequence is that sometimes, if you upgrade to a latest release of svnwiki, you might have to update the configuration for your wiki (since the previous semantics for the configuration files may no longer be supported).

This document will always describe how to setup the latest release of svnwiki as well as the latest version in the Subversion repository.

In order to simplify upgrading, we started keeping the following list of changes we make:

r9373
Instead of passing all the parameters to the svnwiki-post-commit-hook program in the post-commit hook script for your Subversion repository, now you only pass it NAME.
r9602
You no longer specify TMP-PATH in /etc/svnwiki/config.scm.
r10296
You no longer need to create a separate redirect.sh or similar script to use as the ErrorDocument. Instead, you can now use the svnwiki CGI application directly as the ErrorDocument. Of course, if you're already using a redirection script as your ErrorDocument (which was required before this revision), you can continue to use it and nothing will break.

Last update: 2008-11-08 (Rev 14694)

svnwiki $Rev: 14721 $