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.

• Apache (or another web server)
• PHP 5.1.2+
• PHP's GD extension with libGD 2 is recommended but not required

Download and unpack the program:

DOKUWIKI_VERSION='2016-06-26a'
wget http://download.dokuwiki.org/src/dokuwiki/dokuwiki-$DOKUWIKI_VERSION.tgz
tar xfz dokuwiki-$DOKUWIKI_VERSION.tgz
rm dokuwiki-$DOKUWIKI_VERSION.tgz
sudo mkdir -p /usr/local/share/dokuwiki
sudo rm -f /usr/local/share/dokuwiki/$DOKUWIKI_VERSION
sudo cp -r dokuwiki-$DOKUWIKI_VERSION /usr/local/share/dokuwiki/$DOKUWIKI_VERSION

We're going to use .htaccess to enable mod_rewrite for nice looking URLs. NOTE: Be sure to update the auto_prepend_file path.

sudo sh -c 'cat > /usr/local/share/dokuwiki/.htaccess' <<'EOF'
## We don't need to allow index files. We do need to allow symlinks though.
Options -Indexes +FollowSymLinks
 
## Make sure nobody gets the htaccess, README, COPYING or VERSION files
<Files ~ "^([\._]ht|README$|VERSION$|COPYING$)">
    Order allow,deny
    Deny from all
    Satisfy All
</Files>
 
## Add a configuration file to define the top-level directory for the given instance.
php_value auto_prepend_file '/usr/local/share/dokuwiki/preconfig.php'
 
## Enable nice-looking URLs.
RewriteEngine on
 
# Allow static content from outside of DokuWiki.
RewriteCond %{DOCUMENT_ROOT}/static/%{REQUEST_URI} -f
RewriteRule .*                        static/%{REQUEST_URI}        [QSA,L]
RewriteRule ^static/.*                -  [QSA,L]      
 
# Real pages that we need to allow access to. Note that we don't use RewriteCond %{REQUEST_FILENAME} !-f for these.
RewriteRule ^doku.php                 -  [QSA,L]
RewriteRule ^feed.php                 -  [QSA,L]
RewriteRule ^lib/                     -  [QSA,L]
 
# Media and other supporting files.
RewriteRule ^_media/(.*)              lib/exe/fetch.php?media=$1   [QSA,L]
RewriteRule ^_detail/(.*)             lib/exe/detail.php?media=$1  [QSA,L]
RewriteRule ^_export/([^/]+)/(.*)     doku.php?do=export_$1&id=$2  [QSA,L]
 
# Default (home) page.
RewriteRule ^$                        doku.php?id=home  [QSA,L]
 
# All other pages.
RewriteRule (.*)                      doku.php?id=$1    [QSA,L]
EOF

We need to create a shim to set the top-level directory for the site that's loading.

sudo sh -c 'cat > /usr/local/share/dokuwiki/preconfig.php' <<'EOF'
<?php
if ( $_SERVER['DOCUMENT_ROOT'] == '' ) {
  define ('DOKU_INC', getcwd() . '/');
} else {
  define('DOKU_INC', $_SERVER['DOCUMENT_ROOT'] . '/');
}
EOF

# Ensure template directory exists.
sudo mkdir -p /usr/local/share/dokuwiki/templates
sudo chown $USER /usr/local/share/dokuwiki/templates
 
# Get the vector template.
wget -O vector.tgz http://andreas-haerter.com/downloads/dokuwiki-template-vector/latest
tar xfz vector.tgz -C /usr/local/share/dokuwiki/templates
 
# Get the greensteel template.
wget -O greensteel.zip http://syntaxseed.com/project/dokuwikithemegreensteel/download/
unzip -d /usr/local/share/dokuwiki/templates greensteel.zip
 
# Replace greensteel's green gradiant with a blue gradiant.
wget -O /usr/local/share/dokuwiki/templates/greensteel/images/background_repeat.gif 'http://i-tools.org/gradient/exec?submit=1&type=topbottom&size=100&colors=020A75+404DD0&reverse=0&rotate=0&format=gif&alphacolor=%23000000'
 
# Make greensteel's background match the gradiant. Make its links match the background color.
cat > /usr/local/share/dokuwiki/templates/greensteel/style.local.ini <<'EOF'
[stylesheets]
css/custom.css      = screen
[replacements]
__background_site__ = "#404DD0"
__link__            = "#404DD0"
__existing__        = "#404DD0"
EOF
 
# Make sure we can read the footer when using the greensteel template.
cat > /usr/local/share/dokuwiki/templates/greensteel/css/custom.css <<'EOF'
#dokuwiki__footer {
    background: white;
}
EOF
 
# Replace greensteel's logo with a transparent 1x1 icon -- effectively removing the logo.
wget -O /usr/local/share/dokuwiki/templates/greensteel/images/logo.png http://upload.wikimedia.org/wikipedia/commons/c/ca/1x1.png 
 
# Install some custom templates that we maintain in GitHub.
git clone git@github.com:boochtek/dokuwiki-templates.git /usr/local/share/dokuwiki/templates
 
# 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; do sudo ln -sf /usr/local/share/dokuwiki/templates/$template /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/lib/tpl/ ; done

Copy and link the DokuWiki files as appropriate into the site.

SITE='wiki.boochtek.com'
cd /var/www/$SITE
if [ ! -e conf ]; then
  cp -r /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf .
fi
if [ ! -e data ]; then
  cp -r /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/data .
fi
chgrp -R www-data conf data
chmod -R g+w conf data
mkdir -p public static
sudo ln -s /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/{bin,inc,lib,vendor,doku.php,feed.php} public/
sudo ln -s /usr/local/share/dokuwiki/.htaccess} public/
(cd public; sudo ln -s ../{conf,data,static} .)
 
# 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

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 –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

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

sudo curl http://meta.wikimedia.org/wiki/Spam_blacklist?action=raw  2>/dev/null | grep -v '<pre>' > /var/www/wiki.boochtek.com/wordblock.conf 
sudo rm /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf
sudo ln -s ../../wordblock.conf /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf
sudo sh -c 'cat > /etc/cron.daily/dokuwiki-spam-blocklist-download' <<EOF
# Back up the existing wordblock file.
cp /var/www/wiki.boochtek.com/wordblock.conf /var/www/wiki.boochtek.com/wordblock.conf.BAK
# Download the latest spam_blacklist from WikiMedia.
curl http://meta.wikimedia.org/wiki/Spam_blacklist?action=raw 2>/dev/null | grep -v '<pre>' > /var/www/wiki.boochtek.com/wordblock.conf
# If the file we downloaded is less than 10000 lines, revert to the backup.
if [ `wc -l /var/www/wiki.boochtek.com/dokuwiki-2009-12-25/conf/wordblock.conf | cut -d' ' -f1` -lt 10000 ] ; then
  mv /var/www/wiki.boochtek.com/wordblock.conf.BAK /var/www/wiki.boochtek.com/wordblock.conf
fi
EOF
sudo chmod +x /etc/cron.daily/dokuwiki-spam-blocklist-download

Installed the following plugins:

• markdownextra - Markdown syntax inside of <markdown> tags
• editx - rename/move pages (2011-02-06 release)
• comment - source-only notes (GitHub master as of 2010-11-22)
• note - asides, notes, warnings, etc. (2009-06-15 release)
• blockquote - blockquote w/ citation ( rauschen's GitHub branch)
• discussion - user comments/discussion (2010-11-16 release)
• folded - hide/show sections of text (2011-04-13 release)

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

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
sudo mkdir -p /usr/local/share/dokuwiki
sudo rm -f /usr/local/share/dokuwiki/$DOKUWIKI_VERSION
sudo cp -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; do sudo ln -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)
sudo tar 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/
for file in $(cd /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf >/dev/null ; ls); do
  ln -sf /usr/local/share/dokuwiki/$DOKUWIKI_VERSION/conf/$file conf/$file
done
 
# 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.
sudo rm -rf data/cache/*
rm -rf data/index/*
 
# Regenerate the site index.
(cd public ; php -d auto_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.

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

Create the conf/users.auth file:

cd /var/www/wiki.boochtek.com/public
sudo touch conf/users.auth.php
sudo chown www-data:www-data conf/users.auth.php
sudo chmod 440 conf/users.auth.php

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

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

Create the conf/acl.auth.php file:

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

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

*               @ALL          1
*               @user         15
*               @admin        255

• We could/should probably move the bin directory out of public.
• 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.
  • Also make sure to reduce indexdelay setting.
  • Also make sure robots meta tag is the way we want it.
• 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.
• Add table editor plugin.