Creating a Wiki with kwiki
Posted by Steve on Fri 16 Dec 2005 at 16:15
Wikis are simple interactive websites which are extremely easy to use for storing easily updated text content. Using a Wiki you can easily create a lot of content with hyperlinks between them. Debian has packaged several different Wiki systems and here we'll look at installing just one of them: KWiki.
Wikis have become familiar to many people thanks to the popularity of large sites such as Wikipedia and can be very useful for creating collaborative websites.
Whilst there are many Wiki packages included in the Debian GNU/Linux distribution I've always had a soft spot for KWiki due to its simplicity, Perl nature, and low requirements.
Installing the software under Debian is very simple and we will show how to setup a new installation using the Debian Apache2 webserver package.
To get started you'll need to install the software:
wiki:~# apt-get install kwiki Reading Package Lists... Done Building Dependency Tree... Done The following extra packages will be installed: perl perl-modules Suggested packages: libterm-readline-gnu-perl libterm-readline-perl-perl Recommended packages: perl-doc The following NEW packages will be installed: kwiki perl perl-modules 0 upgraded, 3 newly installed, 0 to remove and 0 not upgraded. Need to get 5527kB of archives. After unpacking 22.6MB of additional disk space will be used.
(Yes the hostname for this machine is Wiki, it is a virtual installation of Debian Sarge running on Xen :)
Assuming that you already have an Apache2 server setup the next thing to do is configure the server to run the wiki. This is a three-step process of:
- Creating the virtual host.
- Enabling the execution of CGI scripts.
- Installing an instance of the Wiki software.
Creating the virtual host should be a simple matter of adding a file into the /etc/apache2/sites-available directory specifying the details of your Wiki installation.
I host my websites beneath the /home/www directories so I create directories for the files, and for the logs with these two commands:
wiki:~# mkdir -p /home/www/wiki.my.flat/htdocs wiki:~# mkdir -p /home/www/wiki.my.flat/logs
(Sensible administrators will almost certainly ensure that the logfiles end up in a dedicated logging partition; but that is an issue I'm not going to consider here.)
Now that these directories have been setup we can create the matching Apache configuration file /etc/apache/sites-available/wiki.my.flat:
<VirtualHost *> DocumentRoot /home/www/wiki.my.flat/htdocs ServerName wiki ServerAlias wiki.my.flat # To use CGI scripts outside /cgi-bin/: AddHandler cgi-script .cgi # Our site runs via one single .cgi file. DirectoryIndex kwiki.cgi # Document root. <Directory /> Options -Indexes Options +ExecCGI </Directory> # Logfiles ErrorLog /home/www/wiki.my.flat/logs/error.log CustomLog /home/www/wiki.my.flat/logs/access.log combined </VirtualHost>
With this site created we enable it by running:
wiki:~# a2ensite wiki.my.flat Site wiki.my.flat installed; run /etc/init.d/apache2 reload to enable.
(See the previous article maintaining Apache2 sites and modules lists for more details on the Debian-specific a2ensite and a2enmod tools.)
After enabling the site we need to make sure that Apache will execute our CGI scripts. We do that by enabling the mod_cgi module with the command:
wiki:~# a2enmod cgi
Now Apache is all setup, so we can now actually install an instance of the Wiki. The Debian KWiki package comes with a script which sets up a new wiki instance, allowing you to run multiple installations upon a single host. The script is called kwiki-install.
We can use it as follows:
Now that the CGI script has been installed we can load it in our browser:
(I have this hostname setup in DNS so it resolves to the IP address of the Apache server.)
In order for your visitors to be able to actually modify the page contents you must allow the Apache process to write to the various files within the installation.
The simplest way to do that is to run:
wiki:~# cd /home/www/wiki.my.flat/htdocs/ wiki:/home/www/wiki.my.flat/htdocs# wiki:/home/www/wiki.my.flat/htdocs# chgrp -R www-data database/ metabase/ wiki:/home/www/wiki.my.flat/htdocs# chmod +s database/ metabase/
Once you've done that you, and your visitors, may be able to edit the text of any page. The pages themselves are stored beneath the database/ directory - with the editing information stored beneath metabase/metadata/ directory.
To erase some of the "foreign" pages installed by default you could run:
wiki:~# rm /home/www/wiki.my.flat/htdocs/database/%* wiki:~# rm /home/www/wiki.my.flat/htdocs/metabase/metadata/%*
This will just leave you with the basic (English) help files, and sample contents.
Basic configuration of the site may be conducted by editting the installed file config.yaml, this allows you to setup the sites name and other similar things.
Advanced customization is possible by overriding/replacing the classes which are used for the implementation of the site, but that is beyond the scope of this introduction. (There are several existing plugins listed upon the KWiki homepage which you can study if you're interested in creating your own customizations.)