Search:
TOP > yawk Index | List | Info | Search | Blog | PNX | R
 

Installing yawk

Abstract: This file explains how to install yawk and how to configure a first wiki.

1. yawk Installation

1.1 Prerequisites
The installation starts with some preparations that need to be done before the actual installation can begin. You should read this section and make sure that you have everything available before you begin.

1.1.1 Check your gawk version
First of all, check your install version of gawk, run "gawk --version". This should display 

# gawk --version
GNU Awk 3.1.5

or similar, followed by some license and disclaimer stuff. yawk requires at least gawk version 3.1.4. If your installed version is lower update first.

1.1.2 HTTP server
yawk does not require a certain HTTP server as long as it supports CGI scripting. So any server from apache to mini_httpd will do. However, there are two things you should know.

1.1.2.1 The cgi-bin directory
This is the directory where you have to copy the yawk CGI script wiki.cgi. This might be /usr/lib/cgi-bin but consult your server configuration for it.

1.1.2.2 The server's user id
The user id under which the HTTP server is running is important. Since the server executes the CGI script which must be able to store wikifiles, you must make sure that the script has the UNIX file permissions to do so. The best way is to let the webserver own the wiki files and directories which is why you must know the user. Common user ids are nobody and www-data. Again look at what you have configured.

1.1.3 Get the yawk package
Ok, this one is easy. Fetch the latest yawk tarball from the download directory and untar it somewhere on your server.

1.1.4 Decide on directories for scripts and configuration files
You need two additional directories for yawk. One where it finds its wiki configuration files and one where you store the additional scripts that come with yawk. The recommended default are /etc/yawk for the configuration files and /usr/lib/yawk for the scripts.

If /etc/yawk is not your choice for the configuration directory, see 1.4 below how to adjust the CGI script.

1.1.5 Think about the wiki directories
This is nothing to decide yet but something you should think about: where do you put the wiki directories? Every wiki gets its own directory where it put its data files. yawk make no assumptions about the locations of the directories. That is, you are free to put them were ever you want. I prefer to collect all the wiki directories in one location near to the server's webspace. If the server's document root is under /var/www/my-server/data, then the wiki directories go into /var/www/my-server/wiki-space. It's not required (or recommended) that the wiki files are inside your webspace.

1.2 Install the program files
yawk comes with a total of four scripts: the CGI itself and three additionals. Assuming that your CGI directory is /usr/lib/cgi-bin and you decided to put the additional script into /usr/lib/yawk the installation is like 

# tar xzvf yawk-2.x.y.tar.gz
# cd yawk-2.x.y
# mkdir -p /usr/lib/cgi-bin
# cp wiki.cgi /usr/lib/cgi-bin/
# mkdir -p /usr(lib/yawk
# cp wiki-parser wiki-receiver wiki-relsearch /usr/lib/yawk/

1.3 Adjust the global yawk configuration
yawk's CGI script must be configured for some global settings. There are two locations: the global configuration file yawk.conf and the script itself (see 1.4 below). The recommendation is to adjust both, the configuration file and the script.

1.3.1 Create yawk configuration directory
Create the directory for the wiki configuration files: 

# mkdir /etc/yawk

or whatever your choice is.

1.3.2 Edit the global configuration file yawk.conf
Assumming /etc/yawk is the global configuration directory you should edit the file /etc/yawk/yawk.conf to look like 

configdir    /etc/yawk
bindir       /usr/lib/yawk
configdelim  ,

1.4 Modify the CGI's initial BEGIN block
This step finalises yawk's global configuration. Open the installed CGI script (using the defaults this is /usr/lib/cgi-bin/yawk). There's a BEGIN block at the top of the script which should be edited to adjust the global settings. The block should look like 

BEGIN {
	configdir = "/etc/yawk";
	bindir = "/usr/lib/yawk";
	yawkconf = "/etc/yawk/yawk.conf";
	configdelim = ",";
	}

Done.

2. Wiki Configuration

2.1 Prerequisites
As for the installation there are some things to have ready before you start to configure a wiki.

2.1.1 Choose a wiki key
Every wiki needs to have a unique key. The key is used in two places.

  1. It defines then name of the wiki configuration file, which if key-wiki.conf.

  2. It is part of the wiki URL. For any wiki it's top URL is http://www.example.com/cgi-bin/wiki.cgi/-key/.

Valid characters for the key are letters and digits.

If yawk doesn't find the wiki key in the request URL, it assumes main as key.

2.1.2 Choose a directory
As said above you are free to put you wiki directories wherever you want. If you collect them in on central directory (e.g. /var/www/wikispace) you can of course choose the wiki key as directory name.

2.1.3 The HTTP server's user id
This was already listed as requirement for the installation but here it is used.

2.2 Configure the wiki
The new wiki need a configuration file in yawk configuration directory. Using the recommended defaults this would be /etc/yawk/main-wiki.conf for your first wiki. Open this file and configure at least the wiki directory. 

# /etc/yawk/main-wiki.conf

dir     /var/www/wikispace/main-wiki

This is the only required option you have to set. See wiki configuration for more information.

2.3 Create the wiki directory
The next thing to do is to create and adjust the wiki directory. 

# mkdir /var/www/wikispace/main-wiki
# chown www-data.www-data /var/www/wikispace/main-wiki

Of course, this assumes that your HTTP server runs as www-data.

2.4 Create the first wikifile
Now that the file is fully configured you should test that ot is working by creating a file in it.

Open the URL http://my-server.example.com/wiki.cgi/ in your browser. If your wiki does not have main as key the URL is http://my-server.example.com/wiki.cgi/-key/. Choose Edit from the wiki navigation, type some text and press Save. If this brings you to the wikifile showing the text you typed everything is working as it should.

< dag | at | awk-scripting.de >

TOP > yawk Index | List | Info | Blog | TOP | R