These instructions detail how to install DokuWiki (2005-09-22) on our Debian 3.1 system.

• Apache
• PHP (currently 4.3.x only)
  • PHP's GD extension with libGD 2 is recommended but not needed

Download and unpack the program:

cd /home/web/wiki.sluug.org/
wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-2005-09-22.tgz
tar xfz dokuwiki-2005-09-22.tgz
mv dokuwiki-2005-09-22/* dokuwiki-2005-09-22/.ht* .
rmdir dokuwiki-2005-09-22/
rm dokuwiki-2005-09-22.tgz
touch data/changes.log
chown -R www-data:www-data * .ht*

Edit the .htaccess file. Make it look like this:

## We don't need to allow index files.
Options -Indexes
 
## Don't allow access to the .htaccess file.
<Files ~ "^\.ht">
      Order allow,deny
      Deny from all
      Satisfy All
</Files>
 
## Enable nice-looking URLs.
RewriteEngine on
RewriteRule ^lib/                     -  [L]
RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1   [QSA,L]
RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
RewriteRule ^$                        doku.php?id=home  [QSA,L]
RewriteRule (.*)                      doku.php?id=$1    [QSA,L]

Copy the example configuration file to use as a base:

cp conf/local.php.dist conf/local.php

Edit the conf/local.php file to look like this (make sure it doesn't have any blank lines outside the PHP tags):

<?php
$conf['title'] = 'SLUUG Wiki';
$conf['start'] = 'home';           // Name of the default page.
$conf['superuser'] = 'admin';      // Set the admin user.
$conf['userewrite'] = 1;           // We're using mod_rewrite to make pretty URLs.
$conf['useslash'] = 1;             // Use slashes to separate namespaces, instead of colons.
$conf['target']['interwiki'] = ''; // Don't pop up a new window for Interwiki links.
$conf['target']['extern'] = '';    // Don't pop up a new window for external links.
$conf['breadcrumbs'] = 1;          // Only show 1 previous page.
$conf['htmlok'] = 1;               // Allow editing of raw HTML tags.
$conf['usewordblock'] = 0;         // Don't block posts using "banned" words.
$conf['mailguard'] = 'visible';    // Use "name [at] domain [dot] com" format to display email addresses.
#$conf['useacl'] = 1;               // TODO: Have to create users (manually).
#$conf['authtype'] = 'plain';       // User IDs are stored in a flat file.
#$conf['openregister'] = 1;         // Users may register themselves.
#$conf['defaultgroup'] = 'user';    // Users registering themselves belong to this group.
?>

Create a place to store our backup files, and make sure it's not readable by anyone:

mkdir -p /var/backups/web
chmod -R 600 /var/backups/web

Create the backup script in /etc/cron.daily/backup-dokuwiki:

#!/bin/sh
 
DATE=`date +'%Y%m%d'`
BACKUPDIR=/var/backups/web
EXCLUDE='data/cache/*'
INCLUDE='data/ conf/'
WIKIDIR=/home/web/wiki.sluug.org/
 
tar cfz $BACKUPDIR/wikidata-$DATE.tgz -C $WIKIDIR --exclude="$EXCLUDE" $INCLUDE

Make the script executable:

chmod 755 /etc/cron.daily/backup-dokuwiki

Run the script to test that it works, and saves a file in /var/backups/web/. Run 'tar tfz' on the resulting backup file to make sure it contains files in the data and conf directories.

TODO: Copy the files in /var/backups off the server.

Browse to the wiki and make sure it shows up.

Try to edit a page. Make sure it saves OK.

Make sure history feature ("Old revisions") works.

On January 7, 2006, the wiki started getting the following error intermittently:

Fatal error: session_start(): Failed to initialize storage module: user
(path: /var/lib/php4) in /home/web/wiki.sluug.org/inc/init.php on line 50

Searching Google found this to be a long-standing unresolved PHP bug. The following patch was added, per some suggestions on the bug-discussion page. It seems to have resolved the issue.

--- inc/init.php.ORIG   2005-09-22 12:21:13.000000000 -0500
+++ inc/init.php        2006-01-08 01:18:51.000000000 -0600
@@ -45,6 +45,14 @@
   // make session rewrites XHTML compliant
   @ini_set('arg_separator.output', '&');

+// Possible work-arounds for error we've experienced:
+//    Fatal error: session_start(): Failed to initialize storage module: user 
+//    (path: /var/lib/php4) in /home/web/wiki.sluug.org/inc/init.php on line 50
+// Error is detailed at http://bugs.php.net/bug.php?id=25876
+// Added 2006-01-08 by Craig Buchek.
+session_module_name("files");
+ini_set("session.save_handler", "files");
+
   // init session
   session_name("DokuWiki");
   if (!headers_sent()) session_start();

Here are the steps taken to upgrade to version 2007-06-26b.

First we create a backup of the existing site.

cd /home/web
tar cfz /var/backups/web/wiki.sluug.org.BACKUP-`date +%Y%m%d`.tgz wiki.sluug.org

Download and unpack the new version.

export VERSION=2007-06-26b
wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-$VERSION.tgz
tar xfz dokuwiki-$VERSION.tgz
rm dokuwiki-$VERSION.tgz

Read through dokuwiki-$VERSION/.htaccess to look for anything new.

diff -u wiki.sluug.org/.htaccess dokuwiki-$VERSION/.htaccess | less

In our case, we added the following to the wiki.sluug.org/.htaccess file:

RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]

Read through the dokuwiki-$VERSION/conf/dokuwiki.php file to look for any new config options.

diff -u wiki.sluug.org/conf/dokuwiki.php dokuwiki-$VERSION/conf/dokuwiki.php | less

Double-check to see if there are any patches in the old version of DokuWiki. If so, you'll probably have to manually apply the patches to the new version. (Check to ensure they're still needed first though.) In this case, I manually added the patch listed above.

find wiki.sluug.org -name '*.ORIG*'

Delete the old caches, since we don't need it, and the formats may have changed between versions. We can also use the new help pages (in the wiki namespace), so we can delete them from the old site.

rm wiki.sluug.org/data/cache/* -rf
rm wiki.sluug.org/data/pages/wiki -rf

Copy all the configuration info and data over from the old site to the new site.

cp wiki.sluug.org/conf/{local.php,acl.auth.php,users.auth.php} dokuwiki-$VERSION/conf/
cp wiki.sluug.org/.htaccess dokuwiki-$VERSION/
cp -a wiki.sluug.org/data/* dokuwiki-$VERSION/data/

Check to see if there are any custom templates in wiki.sluug.org/lib/tpl (besides the default template). We don't use any (yet), so we don't need to copy anything over.

Re-create the sitemap file.

touch dokuwiki-$VERSION/sitemap.xml.gz

Correct the ownership so that the web server can write to where it needs to.

chown -R www-data:www-data dokuwiki-$VERSION

Switch over to the new version.

mv wiki.sluug.org wiki.sluug.org.OLD
mv dokuwiki-$VERSION wiki.sluug.org

Test the site. Make sure you can browse to a few different pages. Also make sure you can edit and save a page. Once you're comfortable that the upgrade went OK, you can delete the wiki.sluug.org.OLD directory.

Create the conf/users.auth file:

touch conf/users.auth
chown www-data:www-data conf/users.auth
chmod 440 conf/users.auth

Add an admin account in the file (replace $WIKI_ADMIN_PWD with real password):

# echo "admin:`echo -n '$WIKI_ADMIN_PWD' | md5sum | awk '{print $1;}'`:Administrator:webmaster@sluug.org:admin,users" >> conf/users.auth

Create the conf/acl.auth file:

cp conf/acl.auth.dist conf/acl.auth
chown www-data:www-data conf/acl.auth
chmod 440 conf/acl.auth

Edit the conf/acl.auth file to look something look this:

*               @admin  255
*               @ALL    7
private:*       @admin  255
private:*       @ALL    0
readonly:*      @admin  255
readonly:*      @ALL    1

Copy the files in /var/backups off the server. Delete older versions, or at least create a subdirectory structure.

Accounts/ACLs. See documentation. Set admin's password.

Turn on wordblock to ban edits with certain words (to prevent spamming and profanity)? May not be necessary if we implement ACLs and require users to log in to make edits, except for limited areas.

See if we have the PHP GD extension and libgd2.

Consider changing these config values: fetchsize, registernotify, gzip_output, pluginmanager, hidepages, sitemap

We should make sure there's a robots.txt file for the Wiki site.

We might want to consider setting permissions, so that local users can't read protected stuff. However, I don't think we're going to ever have any content that truly needs protecting.

Initially installed, configured, and documented by Craig Buchek, 2005-09-10. Updated to newer versions on 2005-11-26 and 2007-05-09.