You are looking at historical revision 17704 of this page. It may differ significantly from its current revision.

qwiki

Description

A fast and light-weight wiki

Author

Ivan Raikov and Peter Bex

Requirements

Documentation

qwiki is the "quick wiki". It is a lightweight wiki which uses sxml for internal wiki page representation. Because it uses sxml as intermediate representation, it is easy to write different output generators through the use of multidoc.

In the future we also hope to support multiple storage backends but right now subversion is the only implementation of that.

How to set it up

Set up hyper-estraier

You should set up a Hyper Estraier server. This is as simple as navigating to the directory under which you want the database to be created and entering the following commands:

 # estmaster init estraierdb
 # estmaster start estraierdb

This creates the db and sets the server running.

Later, if you are happy with the setup and the wiki is working properly, you can add this line to your startup scripts:

 estmaster start -bg /path/to/estraierdb

The -bg switch puts it into daemon mode (and makes it quiet).

Create a subversion repository

You should first create a subversion repository, if you don't already have one. Then, make a post-commit-hook script that invokes qwiki-post-commit with as its first argument the repository location and second the newly created revision (currently unused):

 #!/bin/sh
 
 # The path to the web root where the cached HTML files will be placed
 export QWIKI_WEB_PATH=/var/www/html/qwiki
 
 # The place where you have the checkout of this repository
 export QWIKI_SOURCE_PATH=/var/www/private-data/qwiki-checkout
 
 # An URL pointing at the estraier server set up in the previous step
 export QWIKI_SEARCH_URI=http://admin:admin@localhost:1978
 /usr/local/bin/qwiki-post-commit $@

If you prefer, you can delay setting up the post-commit-hook until after you got the wiki up and running (this is a good idea if people will be committing to the repository while you are setting this up).

Run the installation script

Now you are ready to run the qwiki installation script which will create an initial checkout, process all files to make a cached HTML file and create populate the search index.

 # qwiki-install <repos-uri> <checkout-path> <web-path>
<repos-uri>
the URI for the subversion repository from where a copy can be checked out
<checkout-path>
the path to where the checkout of the repository will be stored
<web-path>
the path used by the web-server to serve wiki pages

<checkout-path> and <web-path> should not overlap.

The exact directory locations are up to you, of course, but they will have to match the locations of the post-commit-hook. You can also set the search URI location through the QWIKI_SEARCH_URI environment variable if you changed the default admin account or want it to use some other location than localhost.

Create a spiffy configuration

Currently qwiki can only run under Spiffy, so you will either have to run spiffy as your main webserver, or proxy all requests for the wiki to it.

(use spiffy qwiki qwiki-nowiki qwiki-search qwiki-svn)

;; If you don't want these extensions, remove them from this script
(nowiki-install!)
(search-install!)

(qwiki-repos-uri "file:///path/to/repos")

;; Ensure this is an absolute path, if you are using Chicken 4.1 or earlier
(root-path "/var/www/html/qwiki")

;; Pass all requests to non-existent files through qwiki:
(vhost-map `((".*" . ,(lambda (continue)
                        (parameterize ((handle-not-found qwiki-handler))
                           (continue))))))

(start-server)

When you run this, your qwiki installation should be available at http://localhost:8080

Customizing Qwiki

[parameter] (qwiki-css-file [FILE])

Set an optional CSS file to use for styling the wiki. FILE should be a string, which is parsed into an uri-common object by the uri-reference procedure. This URI should be relative to the docroot.

Changelog

License

 Copyright (c) 2009, Ivan Raikov and Peter Bex
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.