svnblog_how_to

1. Introduction
2. Install Chicken Scheme
3. Install and configure Subversion
4. Configure Apache
   1. Load Apache Modules
   2. Configure mod_dav_svn
5. Install required Chicken extensions
6. Install svnblog
   1. Creating svnblog repository
   2. Svnblog modus operandi
      1. BASE directory
      2. PATH-IN directory
      3. PATH-OUT directory
   3. Mandatory directories for your blog

Edit Link Top

Introduction

svnblog is a system for creating web blogs out of Subversion repositories. The posts are represented in wiki format (using the syntax implemented by svnwiki). When executed (probably as a post-commit hook in your Subversion repository), svnblog downloads/updates a copy of the repository, reads its contents and generates the files (mostly HTML and XML) that you should be visible in your web tree.

This document explains how to download, install and use this great piece of art.

The basic steps are:

• Install Chicken Scheme. This is required because svnblog its written on this programing language.
• Configure Subversion (involved configuring Apache).
• Create a subversion repository for svnblog.
• Create some directories on your repository.
• Set some subversion some properties.

Edit Link Top

Install Chicken Scheme

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

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.

IMPORTANT: Please use Chicken 2.0 or a newer release. Although it is possible to use svnblog with previous versions, you'd need to modify some files.

Edit Link Top

Install and configure Subversion

As svnblog depends on Subversion, you will need to have it installed in the machine you plan to run it on. svnblog 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:

• In Debian, use libsvn0-dev.
• In other distributions try with subversion-devel (which, if your distributor did her work correctly, should install the C header files for the APR library as a dependency).

Once you've built svnblog, you can uninstall all the development libraries.

Edit Link Top

Configure Apache

This section describes the steps required to setup HTTP access to your Subversion repositories (that you'll create soon). There are many other ways to setup Apache.

Edit Link Top

Load 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 former is usually bundled in a separate package:

• In Debian, install libapache2-svn.

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.

Edit Link Top

Configure mod_dav_svn

At this point you'll need to setup a Location in your Apache configuration for the path where your repository will live. You could achieve this with the following info:

<Location /repos>
    DAV svn
    SVNParentPath /home/svn/repos

    # anonymous first
    Satisfy Any
    Require valid-user

    # authenticating them valid ones
    AuthType Basic
    AuthName "Dummy Subversion Repository"
    AuthUserFile /home/svn/access/users
</Location>

• In Debian you'll probably want to store it in /etc/apache2/mods-enabled/dav_svn.conf and make sure there's a link to that file in /etc/apache2/mods-available/.
• In FreeBSD you'll want to add this to httpd.conf.

Edit Link Top

Install required Chicken extensions

You will need to install the following Chicken extensions (eggs) from the official list of extensions:

srfi-40

Adds support for streams (as defined in SRFI-40).

sandbox

Allows you to evaluate code in a safe environment.

You will also need to install a few Chicken extensions (eggs) from Alejandro Forero Cuervo's public repository of Chicken extensions (some are already oficial eggs but the versions in Alejandro's repository are updated more frequently):

orders

Simple functionality for specifing orders and sorting objects.

stream-ext

Adds additional standard functionality for using streams.

stream-parser

A macro useful for defining syntax parsers (required by stream-wiki).

stream-wiki

A library to convert from wiki-format to HTML.

svn-client

Wrappers around Subversion's svn-client library

svn-post-commit-hooks

Higher level wrapper around svn-client, providing functionality useful for programs meant to be run from Subversion post-commit hooks.

range-iter

A library to iterate inside n-cubes with subcubes.

stream-pnm

A library to generate PNM images.

graph-pong

A library useful to generate PNM images of events over time. svnblog uses it to generate a graph of posting frequency.

Chicken comes with the chicken-setup program that simplifies the process of installing extensions. You will, however, still need to download them from Alejandro Forero Cuervo's Subversion repository (you could use the official eggs but, currently, they won't work as well as using the latest versions).

It has come to our attention that on some platforms the directory where chicken-setup installs the eggs (usually /usr/lib/chicken or /usr/local/lib/chicken) is not created automatically. You might want to make sure it actually exists.

The entire process of downloading and installing the eggs can be performed by issuing the following command:

chicken-setup srfi-40 sandbox &&
svn checkout http://svn.afc.no-ip.info/svn/home/src/chicken-eggs &&
for ext in orders stream-ext stream-parser stream-wiki svn-client \
           svn-post-commit-hooks range-iter stream-pnm graph-pong; do
  cd $ext && chicken-setup $ext && cd .. ;
done

You'll have to enter yes to install the srfi-40 and sandbox eggs. You'll have to authenticate with the anonymous user and the empty password for the svn checkout command. Note that there are some dependencies among these eggs, so the order in which you install them is important.

Edit Link Top

Install svnblog

As there are no official releases of svnblog, you'll have to use the version from Alejandro Forero Cuervo's Subversion repository. Use the following command to download it:

svn checkout http://svn.afc.no-ip.info:8000/svn/home/src/svnblog/

Use the "anonymous" login, with the empty ("") password.

The trunk directory contains the latest version. Go there and run make. It will call chicken to compile the Scheme files into C files and then compile and link them to produce the svnblog executable.

Edit Link Top

Creating svnblog repository

This a just a method to make your svnblog repository, you can check another if you want, but with this its ok and its using svnadmin tool, this its a example according the httpd.conf file below.

# cd /home/svn/repos
# svnadmin create svnblog

Now we have our repository for svnblog, created on /home/svn/repos/svnblog. More help about svnadmin.

Try to check if mod_dav and your repository works fine accessing to this direction, http://localhost/repos/svnblog/.

Remember, this repository should be accessed by your web user, on many linux distributions, www-data, so, change the owner for all the files on this directory to www-data:www (in my case, www:www).

Edit Link Top

Svnblog modus operandi

svnblog receives the following parameters:

URL

The URL of your repository. If the data for your web log is stored inside one of the subdirectories of the repository, specify the full URL to that directory (rather than the URL to the base of the repository).

USER, PASSWORD

Authentication tokens used to checkout/update the local copy of the repository. You'll usually want to create a svnblog user with read-only access to your repository (or at least to the directory where you store your blog).

BASE

The subdirectory in the repository where your blog is stored. This should be an absolute path (starting at the base of the repository) and should not end in /. If your blog lives in the root of your repository (e.g. doing svn checkout $URL . creates files/, templates/ and all the other Svnblog directories in your current directory), you should use the empty string here.

PATH-IN

A local directory where svnblog should checkout/update a working copy of the repository. Currently it is important not to end this directory on a slash.

PATH-OUT

A local directory where svnblog should produce the output (the actual files you'll make visible on your web tree).

Edit Link Top

BASE directory

In this case it will be /home/svn/repos/svnblog, this is the root of your svnblog repository, you should use an empty string here when execute svnblog binary.

Edit Link Top

PATH-IN directory

Use whatever directory you want, in this how to we will going to use /tmp/svnblog-in. When you make your first commit to your repository it will be created, so dont try to create this.

Edit Link Top

PATH-OUT directory

Make this directory on /tmp, for example, /tmp/svnblog-out, change once again the owner to your web user, www-data.

Edit Link Top

Mandatory directories for your blog

Now we going to create some directories to put work fine svnblog, if you need some extra information try to read the comments at the beginning of the svnblog.scm source file.

First do a svn checkout to check out a working copy from your repository. In this case:

$ svn co http://localhost/repos/svnblog/

OK, you have a copy of your repository, you will need create this directories on this copy:

posts/

Each file here corresponds to a specific post. The name of the file is the title of the post. The files contain information in wiki format. To make a new post you simply add a new file to this directory and commit.

Note that this makes it is impossible to have multiple posts with the same title (which is a good thing).

files/

A list of files which aren't posts but should be published anyway. You can set the svnblog:process property to "wiki→html" or "identity" (default) to specify a function to parse the contents.

templates/

Directory with multiple files with the templates:

post

A template used for the page for each post.

main

A template used for the default page.

main-post

A template used for each post in the default page.

The directory the blog is stored in must have the following subversion properties:

svnblog title

Like svn ps svnblog:title "Foobar" ., this property its obligatory.

svnblog author

Like svn ps svnblog:author "Foo" ., this property its obligatory.

svnblog url

Like svn ps svnblog:author "http://blog.foobar.com" ., this property its obligatory.

svnblog header-start

Not necessary. The initial depth of headers ocurring in the wikis. For example, if 1, a header "== foo" will be show as <h1>.

svnblog pong-count-scale

Not necessary.

svnblog graph-pong-scale

Like svn ps svnblog:graph-pong-scale 200 ., this property its obligatory.