Table of Contents

DokuWiki

These instructions detail how to install DokuWiki on our Debian GNU/Linux system. We're currently running the 2010-11-07 version of DokuWiki.

Requirements

Installation

Download and unpack the program: 

export VERSION=2005-09-22
cd /home/web/wiki.sluug.org/
wget http://www.splitbrain.org/_media/projects/dokuwiki/dokuwiki-$VERSION.tgz
tar xfz dokuwiki-$VERSION.tgz
rm dokuwiki-$VERSION.tgz
rm -f public
ln -s dokuwiki-$VERSION public
cd public
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]

Configuration

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['typography'] = 0;           // Don't convert quotes to fancy version.
$conf['license'] = 'cc-by-sa';     // License of all content. See conf/license.php and conf/license.local.php for choices.
$conf['showuseras'] = 'username';  // Show users' full names, no email addresses or login names.
#$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.

Deactivate the automatic conversion of certain character combinations into different symbols since this destroys the ability to cut/paste commands and sample configuration data from the documentation. For example, DokuWiki was converting –inet=1 into &ndash;inet= which resulted in a single dash when cut/pasted from the browser to another window, with the copied command failing. 

mv conf/entities.conf conf/entities.conf.out

Backups

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/public
 
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.

Testing

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.

Upgrading

Here are the steps taken to upgrade to version 2010-11-07.

First, read the changes made in the new release. Make sure you follow any directions specific to the new release.

Then we create a full backup of the existing site. 

cd /home/web/wiki.sluug.org
export OLD_VERSION=2009-12-25
sudo tar cfz /var/backups/web/wiki.sluug.org.BACKUP-`date +%Y%m%d`.tgz dokuwiki-$OLD_VERSION

Download and unpack the new version. 

cd /home/web/wiki.sluug.org
export VERSION=2010-11-07
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.dist to look for anything new. Make any necessary changes. 

diff -u dokuwiki-$OLD_VERSION/.htaccess dokuwiki-$VERSION/.htaccess.dist | less

Read through the dokuwiki-$VERSION/conf/dokuwiki.php file to look for any new config options. Make any necessary changes to conf/local.php in the OLD directory. 

diff -u dokuwiki-$OLD_VERSION/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.) 

find dokuwiki-$OLD_VERSION -name '*.ORIG*'

Delete the old cache and index, since they can be regenerated, 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. 

sudo rm dokuwiki-$OLD_VERSION/data/cache/* -rf
sudo rm dokuwiki-$OLD_VERSION/data/index/* -rf
sudo rm dokuwiki-$OLD_VERSION/data/pages/wiki -rf

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

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

Get rid of the files that we don't need. 

mv dokuwiki-$VERSION/conf/entities.conf dokuwiki-$VERSION/conf/entities.conf.dist
rm dokuwiki-$VERSION/{install,index}.php

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

Re-index the site. 

php dokuwiki-$VERSION/bin/indexer.php -c

Correct the ownership and permissions so that the web server can write to where it needs to, and so admins can also write files within the directory. 

sudo chown -R www-data:www-data dokuwiki-$VERSION
sudo chmod -R g+w dokuwiki-$VERSION

Switch over to the new version. 

rm public
ln -s dokuwiki-$VERSION public

Test the site. Make sure you can browse to a few different pages. Also make sure you can edit and save a page. Check out the search feature, backlinks, and old revisions.

Once you're comfortable that the upgrade went OK, you can delete the directory for the previous version of DokuWiki. 

rm -rf dokuwiki-$OLD_VERSION

Enable ACLs and User Accounts

This is a minimal implementation with a single account

The sole purpose is to reduce defacement and overhead from recovery.

Go to the DokuWiki configuration directory 

cd /home/web/wiki.sluug.org/public/conf

Install the skeleton authorization files 

cp -ip users.auth.php.dist users.auth.php
cp -ip acl.auth.php.dist acl.auth.php

Create a backup of the main config file 

cp -ip local.php local.php.090219

Edit local.php using your favorite editor to uncomment the useacl line: 

$conf['useacl']       = 1;        // Enable Access Control List authorization

Create a new account using your web browser:

  1. Point the web browser at http://wiki.sluug.org/
  2. Select the "Login" button at the bottom of the page.
  3. Select the "Register" link.
  4. Fill in
    1. Username: discuss
    2. Real name: SLUUG Administration
    3. E-mail: (your e-mail address)
  5. Select the "Register" button. You should end up at the login page again.
  6. Read the mail sent to you and login using the generated password.
  7. At the bottom of the page, select the "Update Profile" button.
  8. Change these fields:
    1. E-mail: root@mail.sluug.org
    2. New passsword: (The password for the discuss mailing list archive)
  9. Select the "Save" button.

Edit local.php using your favorite editor to add this line: 

$conf['disableactions'] = 'register';   // Users can't register themselves

Test security using your web browser:

  1. Select the "Logout" button.
  2. Tried editing a page without being logged in, but it let me.
  3. Tried editing a page after closing and restarting the browser, but it let me.

Edit acl.auth.php using your favorite editor to:

  1. Change the authority of the "ALL" group from "8" to "1".
  2. Create a new line in the same format, giving user "discuss" "16" level authority.
*               discuss    16

An attempt to edit the same page (still displayed from the earlier test) still displays the source, but now says that update is not allowed. Refreshing the page, it no longer has the "Edit" buttons.

Test for an authenticated user:

  1. Use the "Login" button, enter the username and password from above.
  2. The Edit buttons are now displayed and able to update this page.

For more information, see the ACL documentation.

TODO

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

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. (I think they might have been installed now, but it was tricky to keep them from installing the entire X library set.)

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

See if there are any new configuration settings we should change.

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.

Credits

Initially installed, configured, and documented by Craig Buchek, 2005-09-10.

Updated to newer versions on 2005-11-26, 2007-05-09, 2008-06-11, 2009-02-19, 2010-01-08.