Table of Contents

DokuWiki

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

We aren't using the Debian packaged DokuWiki, because we want to keep up with the latest versions.

Our installation is rather unusual. We install DokuWiki into /usr/local/share, and mostly use soft links to point our web sites at that directory. This is somewhat similar to the way the Debian packaged version does it, but much simpler. This method allows for easier upgrades, as well as sharing the code amongst multiple sites. On the other hand, it prevents through-the-web installation of plugins.

We also allow mixing static content into the site. To do so, simply place the static content in the static directory, and it will appear within the site. This makes it a lot easier to take a static site and add DokuWiki on top.

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']='BoochTek Wiki';$conf['start']='home';// Name of the default page.$conf['template']='default';$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']=1;// Block posts using "banned" words, to reduce spam.$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';// 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['cssdatauri']=1024;// Maximum byte size of small images to embed into CSS.$conf['useacl']=1;// Use ACLs to restrict who can edit pages on the site.$conf['openregister']=0;// Users may NOT register themselves.$conf['compress']=0;// Compressing CSS (and JS) was causing problems.

We 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

Spam Prevention

We were getting a lot of spam on the wiki, so we enabled the wordblock feature, with blocklist updates downloaded from WikiMedia every day.

Testing

Upgrading

With multiple versions of DokuWiki installed into /usr/local, we can have multiple versions installed at the same time, and we can have different sites running different versions. So upgrading consists primarily of installing a new version, the pointing each site at the new version of the code. The installation portion is as follows (basically the same as above, but it's broken up into a couple pieces above):

# Define the version that we're upgrading to.DOKUWIKI_VERSION='2017-02-19a'# Download and install the new version.wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-$DOKUWIKI_VERSION.tgz
tar xfz dokuwiki-$DOKUWIKI_VERSION.tgz
rm dokuwiki-$DOKUWIKI_VERSION.tgz
sudomkdir-p/usr/local/share/dokuwiki
sudorm-f/usr/local/share/dokuwiki/$DOKUWIKI_VERSIONsudocp-r dokuwiki-$DOKUWIKI_VERSION/usr/local/share/dokuwiki/$DOKUWIKI_VERSION# Make sure the shared templates are seen by the current version of DokuWiki.TEMPLATES=$(\cd/usr/local/share/dokuwiki/templates/&&ls--ignore README.md)for template in$TEMPLATES; dosudoln-sf/usr/local/share/dokuwiki/templates/$template/usr/local/share/dokuwiki/$DOKUWIKI_VERSION/lib/tpl/ ; done

Be sure to read the changes made in the new release. Make sure you follow any directions specific to the new release. Also read through the dokuwiki/$DOKUWIKI_VERSION/conf/dokuwiki.php file to look for any new config options. Make any necessary changes to conf/local.php for each site.

When you're ready to upgrade the sites:

# Define the version that we're upgrading to.DOKUWIKI_VERSION='2017-02-19a'# Define the site we're updating.SITE='wiki.boochtek.com'cd/var/www/$SITE# First we make a full backup of the existing site before upgrading, just in case.BACKUP_DIRS=$(ls-d conf data static public 2>/dev/null)sudotar cfz BACKUP-$(date +%Y%m%d).tgz $BACKUP_DIRS# Link to the new version of DokuWiki.ln-sf/usr/local/share/dokuwiki/$DOKUWIKI_VERSION/{bin,inc,lib,vendor,doku.php,feed.php} public/ln-sf/usr/local/share/dokuwiki/.htaccess public/forfilein $(cd/usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf >/dev/null ; ls); doln-sf/usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf/$file conf/$filedone# Get any updates to the help pages (in the ''wiki'' namespace).rm-rf data/pages/wiki
cp-a/usr/local/share/dokuwiki/$DOKUWIKI_VERSION/data/pages/wiki data/pages/wiki
# Delete the old cache and index, since they can be regenerated, and the formats may have changed between versions.sudorm-rf data/cache/*rm-rf data/index/*# Regenerate the site index.(cd public ; php -dauto_prepend_file='/usr/local/share/dokuwiki/preconfig.php' bin/indexer.php -c)chmod-Rf g+w conf data
# Make sure we've got a sitemap that the web server can update.touch data/cache/sitemap.xml.gz
chgrp www-data data/cache/sitemap.xml.gz
chmod g+w data/cache/sitemap.xml.gz

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.

ACLs and User Accounts

Since the wordblock feature didn't stop the spammers from changing our pages, we had to enable ACLs and logon accounts.